Skip to content

Latest commit

 

History

History
286 lines (255 loc) · 11.9 KB

configuration.md

File metadata and controls

286 lines (255 loc) · 11.9 KB

🔧 Configuration

The environment and configuration can be modified in two ways:

  1. Defining variables in the .env file (optional) and .env.local file (mandatory)
  2. Editing the configuration files in the config/docker/ folder

Let's describe the variables first!

Variables

Summary of variables, where they should be defined, and their default values:

Note: don't be intimidated by the table below, sensible defaults are provided. In fact, you can start a new project with just an empty .env.local file!

Variable .env .env.local Default
Server-related variables
CADDY_VERSION ✅ ❌ 2
SERVER_NAME ❌ ✅ localhost:80, localhost
SERVER_ENABLE_WWW_REDIRECT ❌ ✅ true
CADDY_ADMIN_OPTION ❌ ✅ Environment-based
CADDY_DEBUG_OPTION ❌ ✅ Environment-based
PHP-related variables
PHP_VERSION ✅ ❌ 8
PHP_EXTENSIONS ✅ ❌ See Dockerfile
PHP_DEV_EXTENSIONS ✅ ❌ See Dockerfile
PHP_PROD_EXTENSIONS ✅ ❌ See Dockerfile
COMPOSER_VERSION ✅ ❌ lts
COMPOSER_AUTH ❌ ✅
KNOWN_HOSTS ❌ ✅ bitbucket.org github.com gitlab.com
WRITABLE_DIRS ❌ ✅ public/media/ public/uploads/ var/
Node-related variables
NODE_VERSION ✅ ❌ 18
Database-related variables
MARIADB_VERSION ✅ ❌ 11
DATABASE_URL ❌ ✅
DATABASE_ENABLE_MIGRATIONS ❌ ✅ Environment-based
DATABASE_ROOT_PASSWORD ❌ ✅
DATABASE_ROOT_PASSWORD_HASH ❌ ✅
DATABASE_RANDOM_ROOT_PASSWORD ❌ ✅
Other variables
TZ ❌ ✅
IMAGE_PREFIX ✅ ❌
HEALTHCHECK_RETRIES ✅ ❌ 5
HEALTHCHECK_WAIT ✅ ❌ 5s

Server-related variables

Variable Allowed values Notes
CADDY_VERSION "latest", x, x.y Down to 2.6
SERVER_NAME list Server names(s)/address(es) (space or comma-separated)
SERVER_ENABLE_WWW_REDIRECT "true" or "false" Whether to perform the www redirection to the non-www version
CADDY_ADMIN_OPTION string Caddy admin option, environment-based (admin disabled in production)
CADDY_DEBUG_OPTION string Caddy debug option, environment-based (debug disabled in production)

Further considerations:

  • In production, make sure to include your domain in the SERVER_NAME variable, for example: SERVER_NAME="localhost:80, localhost, example.com"
  • The automatic redirection is enabled for only addresses starting with www. (or https?://www.)
  • When SERVER_NAME contains a www.example.org or https?://www.example.org address, ensure that example.org exists too

PHP-related variables

Variable Allowed values Notes
PHP_VERSION "latest", x, x.y Down to 7.1
PHP_EXTENSIONS list Additional PHP extensions to be installed (space or comma-separated)
PHP_DEV_EXTENSIONS list Additional PHP development-only extensions to be installed (space or comma-separated)
PHP_PROD_EXTENSIONS list Additional PHP production-only extensions to be installed (space or comma-separated)
COMPOSER_VERSION "latest", "lts", x, x.y, x.y.z
COMPOSER_AUTH string Composer authentication, see FAQ
KNOWN_HOSTS list Known hosts for SSH keys retrieval, see FAQ (space or comma-separated)
WRITABLE_DIRS list Folders that need to be writable by the PHP process (space or comma-separated)

Further considerations:

  • WRITABLE_DIRS does not support folder names that contain spaces or commas
  • Default WRITABLE_DIRS ensure compatibility with LiipImagineBundle and the uploads folder (used in many Symfony examples)

Node-related variables

Variable Allowed values Notes
NODE_VERSION x

Database-related variables

Variable Allowed values Notes
MARIADB_VERSION "latest", x, x.y Down to 10.6
DATABASE_URL string Doctrine-style database URL/DNS with "mysql://" and "db:3306"
DATABASE_ENABLE_MIGRATIONS "true" or "false" Whether to perform migrations at startup, environment-based ("true" in production)
DATABASE_ROOT_PASSWORD string Password for the root user
DATABASE_ROOT_PASSWORD_HASH string Hashed password for the root user (SELECT PASSWORD('thepassword'))
DATABASE_RANDOM_ROOT_PASSWORD string Any non-empty value for random root password

Further considerations:

  • If DATABASE_URL specifies a root user with an empty password, password will be honored and DATABASE_ROOT_* ignored

In a non-production environment:

  • If DATABASE_URL is empty, root password will be empty and database name will default to "app"
  • If DATABASE_URL specifies a non-root user and none of the DATABASE_ROOT_* variables are applicable, root password will be empty

In a production environment:

  • If DATABASE_URL is empty, an error is thrown
  • If DATABASE_URL specifies a non-root user and none of the DATABASE_ROOT_* variables are applicable, an error is thrown

Other variables

Variable Allowed values Notes
TZ string Timezone for all services (synced with PHP timezone)
IMAGE_PREFIX string Service image prefix (see FAQ)
HEALTHCHECK_RETRIES number Healthcheck max consecutive failures allowed
HEALTHCHECK_WAIT duration Healthcheck init time (failure ignored in this window)

Configuration files

  • Caddyfile: Caddy development/production configuration
  • mariadb.cnf: MariaDB development/production configuration
  • mariadb.prod.cnf: (Optional) MariaDB production configuration
  • php-fpm.conf: PHP FPM development/production configuration
  • php.ini: PHP development/production configuration
  • php.prod.ini: (Optional) PHP production configuration

Default configuration files are stored in the Docker images: