phd uses an environment variables based configuration, see also Dev/prod parity for more information about this topic. There are basically two levels of configurations handled by environment variables.
Variables for controlling the application stacks (outside, on your host) with
docker-compose, are defined in
.env files residing in the current working directory.
If you are in the project root-folder you work with your dev environment, while you are in the
tests/folder you are working against your test stack, which has ie. an own database.
The structure of the services within a stack are defined in
docker-compose.yml files, you can add or change additional databases or caching services here.
See also hierarchy & scopes below for more information about variables.
:exclamation: Before starting the application the first time, run
make init to create your
tests/.env from to corresponding
.env file in your project root, there is by default just one setting:
This merges the configuration to given YAML files.
You can also set other variables here, like tokens required for running updates in a container. Please note that these variables will not be available when building the Docker image
Please also make sure to not commit the
.env file and not have secrets in any
For testing is it strongly recommended to set a
docker-compose uses the directory name by default and all your containers would be prefixed with
Windows users, use a semicolon as path separator
Environment settings used within the application services (inside a container, such as PHP) are defined in
docker-compose.<CURRENT_ENVIRONMENT>.ymlfiles (environment specific)
Available environment variables for the application are defined in
app.env-distshould be adjusted and committed to reflect basic application settings, but we strongly recommend not to add secrets like passwords or tokens to the repository. Note: The
app.env-distfile is intentionally copied as
app.envonto the image. If you want to make changes during runtime, you also need to create a local file and mount this into the container.
Initial configuration adjustments should be made for the following values:
APP_NAME=myapp APP_TITLE="MyApp" APP_LANGUAGES=en,fr,zh
:build: Within a
phd5-appwe recommend to update
app.env-distsettings, while in a
phd5-templatewe usually update the
Further important settings
YII_ENV- current application environment, eg.
YII_DEBUG- application debug settings
APP_CONFIG_FILE- alias for additional configuration file
APP_MIGRATION_LOOKUP- alias for additional migration paths eg.
For all available environment settings, see
To be able to use translatemanager every defined/used language must be present in the app_language table. You can insert new languages in backend: http://<YOUR_DOMAIN>/translatemanager/language/create
During local development it is recommended to enable debug settings in
:bangbang: Make sure you do not have these settings enabled in production deployments.
You find the config files for an application in
src/config, those can also be changed at runtime during development:
config/main.php- main application configuration entrypoint
config/common.php- configuration for web and console applcations
:exclamation: An important difference between application and environment configuration is that ENV variables are usually immutable by convention.
vendor, shared across environments
The following list displays configuration locations from highest to lowest priority and their corresponding scope; files are located in the application root folder
/ or in the
|Defined in||.yml||bash||app||runtime||restart||rebuild||variable replacement|
:exclamation: Values in
.envmust be explicitly passed to a service configuration in a
ENV variable are immutable by convention, so if a value is set in a
Dockerfile, you can not
overwrite it in your
app.env file, but in
Only values in
app.env can be changed while the containers are running. If you change environment variables in
docker-compose.yml you need to restart your containers.
graph TD subgraph "host" .env docker-compose subgraph "container (bash)" docker-compose.yml docker-compose.local.yml Dockerfile bash subgraph "app" config/app.env config/env-defaults yii end end end bash[/bash/] yii[/yii/] docker-compose[/docker-compose/] config/app.env>config/app.env] .env-.->docker-compose.yml .env-.->docker-compose.local.yml docker-compose.local.yml---docker-compose.yml docker-compose.yml---config/app.env config/app.env---config/env-defaults config/env-defaults---Dockerfile style host fill:#eee style app fill:#fdf
Help us to improve the documentation, fork this page.