wearefrank/frank-framework repository overview

⁠This are old build of the Frank!Framework. The new build can be found on frankframework/frankframework⁠

⁠Frank!Framework

Exchange, modify and aggregate messages between systems!

⁠Open-Source, Low-Code & Stateless

The Frank!Framework is a framework that is completely configurable through XML configurations. Each Frank!Application may contain multiple configurations, and each configuration can consist of multiple end-to-end connections which we call 'adapters'. Configurations may be (re)loaded conditionally or individiually for optimal performance and customizability. The application may be managed and monitored through a web interface or REST API. See it in action: https://frank2example.frankframework.org⁠

⁠Contents

• General use⁠
  • Local use⁠
  • Server use⁠
• Filesystem⁠
  • Directories⁠
  • Files⁠
• Logging⁠
• Environment variables⁠
• Health and readiness⁠
• Considerations⁠
  • HTTPS and authentication⁠
  • Secrets⁠
  • Non-root⁠

⁠General use

The image contains an empty framework-instance that needs to be configured before use.

Whether using the container locally or building your own image for use on servers, refer to Filesystem⁠ information on which directories and files to mount or copy.

For a list of available tags, see https://nexus.frankframework.org/#browse/search/docker⁠.

⁠Local use

To run the image, run the following command, adding environment variables and mounts as needed:

docker run --publish <hostport>:8080 [-e <name>=<value>] [-v <source>:<target>[:<options>]] --name <name> nexus.frankframework.org/frank-framework[:<tag>]

For example, to run Frank2Example on http://localhost⁠ with the latest image using Powershell on Windows:

docker run --publish 80:8080 \
	-e dtap.stage=LOC \
	-v $pwd/example/src/main/resources:/opt/frank/resources \
	-v $pwd/example/src/main/webapp/META-INF/context.xml:/usr/local/tomcat/conf/Catalina/localhost/ROOT.xml \
	--name Frank2Example \
	nexus.frankframework.org/frank-framework:latest

⁠Server use

Please read the Considerations⁠ before using the image on servers, as the default setup might not be secure enough for your use.

For use on servers, you need to build your own image that includes the required configuration files. To start building your own image, start your Dockerfile with:

FROM nexus.frankframework.org/frank-framework[:<tag>]

Use COPY --chown=tomcat when copying files to ensure that tomcat can use the files.

⁠Filesystem

⁠Directories

The image contains the following directories:

⁠Files

The image also contains the following files:

⁠Logging

Generated log files are stored in /usr/local/tomcat/logs.

⁠Environment variables

Environment variables can be used to set parameters. Environment variables have the highest precedence and override parameters set in .property files supplied by Tomcat, resources and configurations.

Environment variables can be used to replace parameters in Tomcat configuration files such as server.xml and context.xml.

Do not use environment variables for secrets!

⁠Health and readiness

The health and readiness of the container can be monitored by polling the /iaf/api/server/health API endpoint. This will return a HTTP statuscode of 200 if all adapters are running and a HTTP statuscode of 503 if there are adapters in a non-running state.

⁠Considerations

The images are based on Tomcat, all restrictions and considerations that apply to Tomcat also apply to using the provided images.

⁠HTTPS and authentication

Frank!Applications use HTTPS and require authentication unless dtap.stage=LOC, but the default server.xml of Tomcat is not configured for inbound HTTPS traffic and user authentication. To configure this, the server.xml file will need to be replaced by either building your own image or mounting it at runtime.

⁠Secrets

Special consideration should be taken with secrets. As described on the Tomcat website⁠, secrets are stored in plain text in the container. To use secrets in your Tomcat and Frank!Application configuration, you can take the following steps:

• In your configuration, use the authAlias attribute with value ${<secret-name>}
• In cases where you need to use username or password separately (such as the Tomcat context.xml), you can set the values to ${<secret-name>/username} and ${<secret-name>/password} respectively
• Mount the value for the username in the file /opt/frank/secrets/<secret-name>/username
• Mount the value for the password in the file /opt/frank/secrets/<secret-name>/password

See the context.xml⁠ of the test-project and corresponding Dockerfile⁠ for an example.

⁠Non-root

This image runs Tomcat as a separate user tomcat:tomcat with UID=1000 and GID=1000 instead of root. If you need to run as root, you will need to set USER root in your Dockerfile.