View Categories

Configuration files

4 min read

Configuration: Files vs Settings

  • The Settings page writes changes to .env.local (never committed).
  • .env holds defaults that are committed.
  • Real OS env vars (exported in the service/host) override both.
  • Never commit secrets. Keep secrets in real env vars or .env.local only.
  • In prod, changes to env may require php bin/console cache:clear (or PHP-FPM reload) to take effect.

Precedence (highest → lowest)

  1. Real environment variables (e.g., export MAILER_DSN=…)
  2. .env.local (your Settings form writes here)
  3. .env.$APP_ENV
  4. .env

What you can change from Settings (writes to .env.local)

Below are the main variables exposed in the UI. When you save, EAC writes/updates the corresponding key in .env.local. The “.env (Present value)” column in the UI is read-only context.

Scheduling & System

  • SCHEDULE_ENABLED
  • SCHEDULE_RESCHEDULE_OLD_TASK_AFTER_X_MIN
  • EAC_CHECK_STATUS_WITH_GIT
  • EAC_CRON_USER
  • EXEC_TASK_AVG_COUNT
  • EAC_DISPLAY_ERROR_ON_HOME
  • PHP_PATH_COMMAND
  • APP_DEFAULT_URI
  • APP_TASK_LOG_TYPE (file or db)
  • APP_JAVA_HOME
  • Paths: APP_CONSOLE, APP_LDIR, APP_DEPLOY_DIR, APP_EXEC_EXTENSION, APP_SCANNED_PARTITIONS, APP_TMP_DIR, APP_UPLOAD_DIR

Mail

  • APP_MAILER_DEFAULT_SENDER
  • APP_MAILER_DEFAULT_RECIPIENTS
  • APP_ENABLE_TASK_MAILER
  • Transport: MAILER_PROTOCOL, MAILER_USER, MAILER_PASSWORD, MAILER_HOST, MAILER_PORT, MAILER_OPTIONS
    • Note: UI masks passwords; saved value goes to .env.local.

Database (core app)

  • DB_DRIVER, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_OPTIONS
    • EAC computes DATABASE_URL from the above.

ETL log tables & ETL logging DB

  • Flags & table names: APP_ENABLE_ETL_LOGS, ETL_STAT_TABLE_NAME, ETL_MET_TABLE_NAME, ETL_LOG_TABLE_NAME
  • Connection (if different from core DB):
    DB_DRIVER_URL_ETL_LOG, DB_HOST_URL_ETL_LOG, DB_PORT_URL_ETL_LOG,
    DB_NAME_URL_ETL_LOG, DB_USER_URL_ETL_LOG, DB_PASSWORD_URL_ETL_LOG, DB_OPTIONS_URL_ETL_LOG
    • EAC computes DATABASE_URL_ETL_LOG from the above.

Security

  • JWT_PASSPHRASE (passphrase only; keys themselves are files, see below)

What stays in files (not editable in Settings)

These are structural or build-time values. Set them in real env vars or in .env / .env.local:

  • APP_ENV (e.g., prod, dev)
  • APP_SECRET (never commit a real secret in .env; use .env.local or OS env)
  • EAC_SERVER_CODE (instance identifier)
  • APP_SITE_ENV (UI banner/env display)
  • COMPOSE_PROJECT_NAME (only relevant if you use Docker)
  • MESSENGER_TRANSPORT_DSN
  • JWT key paths:
    JWT_SECRET_KEY, JWT_PUBLIC_KEY (they point to key files on disk; manage the files at deploy time)
  • Any variable your organization treats as infrastructure (e.g., reverse proxy, PHP-FPM pool names, etc.)

Safe examples

.env (committed defaults — no secrets)

APP_ENV=prod
# Do NOT put the real secret here in git
APP_SECRET=change-me-in-env-local-or-OS

DB_DRIVER=postgresql
DB_HOST=db.example.internal
DB_PORT=5432
DB_NAME=eac_db
DB_USER=eac_usr
DB_OPTIONS=serverVersion=16&charset=utf8

APP_TASK_LOG_TYPE=file
SCHEDULE_ENABLED=true

.env.local (not committed — overrides & secrets)

# Real secrets and instance overrides
APP_SECRET=********REDACTED********
DB_PASSWORD=<strong-db-password>
MAILER_PASSWORD=<smtp-password>

APP_DEFAULT_URI=https://eac.example.com/
PHP_PATH_COMMAND=/usr/bin/php
EAC_CRON_USER=eac

Tip (prod): after changing env in production, run:

php bin/console cache:clear --no-warmup
php bin/console cache:warmup
# or reload PHP-FPM if your stack caches env at master process start

How the Settings form interacts with files

  • On Save, the app writes only the keys it manages to .env.local.
  • The UI shows:
    • “.env.local (updatable)” → the value that will be saved/overridden.
    • “.env (Present value)” → baseline default (read-only).
  • If a key is present in real OS env, that value still wins at runtime.

Sensitive data guidelines

Audit who can access the Settings page (Admin-only).

Put passwords, tokens, secrets in .env.local or real environment variables, never in .env.

Keep JWT keys as files outside of git; reference them via JWT_SECRET_KEY / JWT_PUBLIC_KEY.

Limit file and directory permissions for:

var/eac/log/, var/eac/tmp/, var/eac/uploads/, var/eac/deploy/

What are your Feelings