3. How to configure

There are different ways, how the application is configured. Namely those are

• Environment variables
• Local configuration files

As we follow the 12 factor principles, all main configuration should always happen through environment variables. So why do we support local configuration files at all? Simply to make life as a developer easier: You sometimes may want to add some local configuration, for example add extra logging. Still you don't want to accidentally commit those changes to the repository with the main configuration.

To put it another way: You'll probably only ever use local configuration files during development.

Important: If you find yourself fiddling around with config files on your production servers, you're doing it wrong! Use environment variables instead!

Environment Variables

We will not cover, how you set environment variables on your production system, as this is part of the deployment. You also find some examples in the Docker documentation.

But what about local development? Of course, we also need a way to easily set environment variables to control the app. We have implemented two mechanisms to do so:

• In the environment section of the docker-compose.yml. This requires to remove and recreate the container each time you change a variable. So we recommend to only put ENABLE_ENV_FILE here and use the next option for the rest.
• In a .env file in your app directory. Changes there are picked up immediately by the yii app inside the container. We have included an example .env-example that you can use to get started.

Variables in docker-compose.yml have precedence over those in the .env file.

Note: Variables in the .env file are only available in the Yii PHP application, because we use PHP Dotenv to load them. They are not available for example in bash scripts. So if you need them there, you should add them to docker-compose.yml.

The following environment variables are used by the base image:

Important: Some variables can only be set in the docker-compose.yml (marked with dc-only).

Mandatory:

• COOKIE_VALIDATION_KEY the unique cookie validation key required by Yii.

Optional:

• API_TOKEN (dc-only) the github API token for composer updates.
• ENABLE_ENV_FILE (dc-only) whether to load env vars from a local .env file. Default is 0.
• ENABLE_LOCALCONF whether to allow local overrides for web and console configuration (see below). Default is 0.
• YII_DEBUG whether to enable debug mode for Yii. Default is 0.
• YII_ENV the Yii app environment. Either prod (default) or dev. Do not use test as this is reserved for the testing container!
• YII_TRACELEVEL the traceLevel to use for Yii logging. Default is 0.
• DB_DSN the DSN to use for DB connection. Defaults to mysql:host=db;dbname=web if not set.
• DB_USER the DB username. Defaults to web if not set.
• DB_PASSWORD the DB password. Defaults to web if not set.
• SMTP_HOST the SMTP hostname.
• SMTP_USER the username for the SMTP server.
• SMTP_PASSWORD the password for the SMTP server.

Configuration Files

All configuration lives in three files in the config/ directory.

• web.php configuration for the web application
• console.php configuration for the console application
• params.php application parameters for both web and console application

These three files are committed to your repository, so you should be careful about changes there.

To override some settings during development, without accidentally committing them to the repository, you can create local override files (requires ENABLE_LOCALCONF to be set):

• local.php local overrides for the web configuration
• console-local.php local overrides for the console configuration

Both files are merged with the respective configuration above. This way you can explicitely override specific parts of the web or console configuration.