Configuration #

Certain settings of the FLAT server can be configured using environment variables. The chapter Defining Environment Variables in the Cookbook provides information on how to set environment variables.

Environment Variables #

Setting environment variables is easy. Provide them directly in your docker compose configuration in the environment or the envfile sections:

services:
  flat:
    image: code-registry.avenga.cloud/product/flat/flat/flatrunner
    env_file: my.env
    environment:
      - MY_VAR=my value

General #

• FLAT_SERVER_TYPE: Set to php-fpm and httpd respectively to run PHP-FPM and httpd in separate containers. Leave unset (default) to start both processes in a single container. All other variables in this document except FLAT_STATUS_AUTH apply only to the combined container or the php-fpm container. (→ PHPFPM below)
• FLAT_SERVER_ROLE: This setting is typically used to distinguish production systems from staging or development servers. Its value is accessible in the $server variable as $server/role.
• FLAT_STATUS_AUTH: Username and password, separated by a : for access to the php-fpm and httpd status pages. The pages are disabled entirely if FLAT_STATUS_AUTH is not set. If enabled, the httpd status can be requested via HTTP at /ServerStatus, and the PHP-FPM status at /FPMStatus?full.
• FLAT_STRICT_DEPRECATIONS: set this to true to make requests fail with an error if a deprecated feature is used. Default: false
• FLAT_DEBUG_ALLOW_HEADER: enables per request debugging, defaults to false unless FLAT_DEBUG_AUTH is set.
• FLAT_DEBUG_AUTH: sets a password to protect per request debugging.
• FLAT_UID_FORMAT: use uuid3 or uuid4 to switch the format of the requestID generated in the logs and the id in the DC to UUID version 3 or 4 respectively instead of the Apache httpd unique_id used by default.
• FLAT_USE_XSLT_CACHE: set to false to disable caching for the xslt action, defaults to true.
• FLAT_USER_AGENT: set the default user agent string used by FLAT for outgoing requests, default: FLAT
• FLAT_MAX_PARSE_SIZE: maximum size of text that can be parsed with xml-parse() and html-parse(). Examples: 1048576, "100000 B", "12345 kB", "1.23 MiB"

Request Timeouts #

Note that the maximum allowed overall time for a given request is always limited by FLAT_MAX_TIMEOUT. All other timeouts can be individually adjusted for each request using the appropriate request option.

Use the following environment variables to configure the timeouts used during requests:

• FLAT_DEFAULT_TIMEOUT: Default timeout in seconds for outgoing HTTP requests.
• FLAT_DEFAULT_CONNECT_TIMEOUT: Default connection timeout in seconds for outgoing HTTP requests. If set to 0, the value of FLAT_DEFAULT_TIMEOUT is used.
• FLAT_DEFAULT_TTFB_TIMEOUT: Maximum time in seconds for receiving the first byte.
• FLAT_MAX_TIMEOUT: Maximum allowed time in seconds for outgoing HTTP requests.
• FLAT_MAX_TIMEOUT_PROCESSES: Specifies how many PHP-FPM processes are allowed to wait for slow sources at any one time. The lower the threshold value, the earlier slow sources will be blocked.

php.ini #

Arbitrary directives can be merged into php.ini by setting environment variables starting with PHP_INI_. For example, to set post_max_size to 100 MiB, just export PHP_INI_post_max_size=100M in the environment of the flatrunner or flatphp container:

  environment:
    - PHP_INI_post_max_size=100M

Refer to the PHP documentation for a list of directives.

PHP-FPM #

Some parameters used for PHP-FPM process management can be adjusted using environment variables. Refer to the PHP-FPM documentation for more information.

• FLAT_FPM_MAX_PROCESSES: Controls pm.max_children. Default 100.
• FLAT_FPM_MAX_REQUESTS: Controls pm.max_requests. Default 500. Limits the number of requests each child process executes before it is replaced by a new process.
• FLAT_FPM_MIN_SPARE: Controls pm.min_spare_servers. Default 5. The desired minimum number of idle child processes to be created.
• FLAT_FPM_MAX_SPARE: Controls pm.max_spare_servers. Default 7. The desired maximum number of idle child processes.
• FLAT_FPM_START_SERVERS: Controls pm.start_servers. The default is the average of pm.min_spare_servers and pm.min_spare_servers. The initial number of child processes to be started.
• PHPFPM: hostname of the php-fpm container if separate containers for PHP-FPM and Apache httpd are used (→ FLAT_SERVER_TYPE above). Must be set for the httpd container in case the PHP-FPM container cannot be reached on localhost.

httpd.conf #

Arbitrary directives can be merged into httpd.conf by setting environment variables starting with APACHE_. For example, to set Mutex posixsem, just include APACHE_Mutex=posixsem in the environment of the flatrunner or flatapache container:

  environment:
    - APACHE_Mutex=posixsem

Refer to the Apache HTTP Server documentation for the available directives.

If you want to set a directives more than once (e.g. to set multiple headers), you can append arbitrary strings to the variable name, separated with a _. Those suffixes, including the _ will be removed. For example: APACHE_Header_1='set MyHeader "foo"' and APACHE_Header_2='set MyOtherHeader "bar"' will produce two Header set ... directives.

For more complex configurations, such as <Location>-blocks, you will have to create a new container image and copy files containing those statements into the appropriate directories.

See also #

• Defining Environment Variables (Cookbook)