Docker #

FLAT is available as a set of Docker images. Therefore, to run FLAT, you need to make sure that you have Docker or an alternative means to pull and run Docker images installed on your system. For a production environment we strongly recommend a container orchestration tool, such as Kubernetes, Docker Swarm, OpenShift or Rancher. Additionally, a suitable log server setup like Elasticsearch, Kibana and Logstash is essential for evaluation and analysis of log data generated by FLAT.

Registry Login #

To access the registry you’ll need to authenticate with a suitable token with the read_registry permission. Avenga may provide you with a Project Access Token or with a user account, which you can use to generate a Personal Access Token in your user settings.

You can then login to the container registry with an arbitrary username (e.g. -) and your project access token

$ docker login code-registry.avenga.cloud
Username: -
Password: <project access token>

or with your username and your personal access token:

$ docker login code-registry.avenga.cloud
Username: <first name>.<last name>
Password: <personal access token>

Images #

The latest image provides you with the most recent stable official release. A beta image with brand-new features is also available.

You can download those images for example via

$ docker pull code-registry.avenga.cloud/product/flat/flat/flatrunner:24.0

or just start a container as shown below. Aside from the flatrunner image, you will also need the flatcleancaches image that is used to periodically clean the disk cache, as well as the flatphpstats image that exports some measurements showing the utilization of your FLAT setup.

Container #

As a bare minimum, you can run the server by simply starting the container with docker compose up and the following configuration (docker-compose.yaml or compose.yaml). This is suitable for a simple development or test environment, but not recommended for production use:

services:
  flat:
    image: code-registry.avenga.cloud/product/flat/flat/flatrunner:${TAG:-latest}
    ports:
      - "${PORT:-8080}:${PORT:-8080}"
    environment:
      - PORT=${PORT:-8080}
    volumes:
      - .:/app

Add the TAG environment variable to start a container based on a specific release, for example:

$ TAG=beta docker compose up

or

$ TAG=24.0.0 docker compose up

To have FLAT listen to a different port than 8080 simply set the PORT environment variable accordingly:

$ PORT=8888 docker compose up

Environment #

Besides PORT you might want to add more environment variables to the FLAT container, for example TZ to set or forward the local timezone for date/time calculations.

There are a couple of environment variables to configure FLAT’s behavior.

In a typical development setup the environment section in docker-compose.yaml could look like this:

    environment:
      - PORT=${PORT:-8080}
      - TZ
      - FLAT_SERVER_ROLE=devel
      - FLAT_DEBUG_ALLOW_HEADER=true
      - FLAT_DEBUG=*:warn:log
      - FLAT_USE_XSLT_CACHE=false
      - FLAT_ALLOW_MOCKING=true

Separate PHP-FPM and httpd containers #

Since FLAT 24.0.0, you can optionally run PHP-FPM and httpd in separate containers. This can be leveraged to improve, among others, autoscaler behavior, liveness checks and resource usage. In this mode, the same image is used for both containers, but the process started as the entry point is selected using the FLAT_SERVER_TYPE environment variable.

services:
  flat:
    container_name: flat
    image: code-registry.avenga.cloud/product/flat/flat/flatrunner:${TAG:-latest}
    environment:
      - FLAT_SERVER_TYPE=php-fpm
      - TZ
    volumes:
      - .:/app
    depends_on:
      - flat
    healthcheck:
      test: ['CMD', '/bin/sh', '-c', 'PORT=9000 /opt/avenga/flat/lib/fit/bin/php -d error_log=/proc/self/fd/2 /opt/avenga/fcgiclient/testflat']
      interval: 10s
      timeout: 3s
      start_period: 2s
      retries: 3

  flathttpd:
    container_name: flathttpd
    image: code-registry.avenga.cloud/product/flat/flat/flatrunner:${TAG:-latest}
    ports:
      - "${PORT:-8080}:${PORT:-8080}"
    network_mode: service:flat
    environment:
      - PORT=${PORT:-8080}
      #- PHPFPM=...
    environment:
      - FLAT_SERVER_TYPE=httpd
      - TZ
      - PORT=${PORT:-8080}
      - SERVER_NAME=flat.name
    healthcheck:
      test: ["CMD", "/usr/bin/curl", "-f", "http://localhost:8080/ServerStatus"]
      interval: 10s
      timeout: 3s
      start_period: 2s
      retries: 3

📎 If you have separate containers for PHP-FPM and httpd, and the PHP-FPM container cannot be reached on localhost, the PHPFPM environment variable allows you to set the hostname for the PHP-FPM container.

Additional Container Images #

Aside from the container images that contain the web server and PHP-FPM component, FLAT ships with two additional images that perform auxiliary functions and should be started in the same pods as the main containers.

flatcleancaches Container #

Unless your installation does not make use of FLAT’s internal HTTP Cache, the flatcleancaches container is required to limit the amount of disk space used for the cache.

Environment #

flatphpstats Container #

The flatphpstats container is used to log real time usage information for the PHP-FPM processes. The information should be used to tune the PHP-FPM process management environment variables for your workload and monitor if the values chosen are still appropriate. They can also be used as custom metrics to control your autoscaler.

Logs are formatted as JSON and written to STDOUT. The values correspond to those provided by the PHP-FPM Status Page.

{"type":"fpmstats","timestamp":1708622767,"listen_queue":0,"idle_processes":7,"active_processes":3,"total_processes":10,"slow_requests":0}
{"type":"fpmstats","timestamp":1708623246,"error":"Read timed out"}

Environment #

Example docker-compose.yaml #

To run the server, including the cleancaches and phpstats services, you can use docker compose up with the following configuration (docker-compose.yaml or compose.yaml). This setup is a good basis for a production environment:

services:
  flat:
    image: code-registry.avenga.cloud/product/flat/flat/flatrunner:${TAG:-latest}
    ports:
      - "${PORT:-8080}:${PORT:-8080}"
    environment:
      - PORT=${PORT:-8080}
    volumes:
      - .:/app
      - cache:/var/cache/fit14
    depends_on:
      init:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "/usr/bin/curl", "-f", "http://localhost:8080/test.fit"]
      interval: 10s
      timeout: 3s
      start_period: 2s
      retries: 3

  cleancaches:
    image: code-registry.avenga.cloud/product/flat/flat/flatcleancaches:${TAG:-latest}
    environment:
      - LOG_LEVEL=1
      - CACHE_DISK_MAX_USED=2000
      - CACHE_DISK_MAX_USED_BEFORE_RUN=2200
      - CLEAN_CACHE_REPEAT_TIME=300
    volumes:
      - cache:/var/cache/fit14

  phpstats:
    image: code-registry.avenga.cloud/product/flat/flat/flatphpstats:${TAG:-latest}
    network_mode: service:flat
    environment:
      - MAXERRORS=5
      - DELAY=3

  init:
    image: alpine
    command: /bin/sh -c "chown 1000:1000 /var/cache/fit14/ && chmod g+s /var/cache/fit14/"
    volumes:
      - cache:/var/cache/fit14

volumes:
  cache: