WebHosting

Docker Compose services and Nginx/Apache configuration for the shared web host. Puppet deploys the host configuration and the environment file from Hiera-eyaml.

Environment configuration

The existing variable names and single Puppet-managed .env file remain the deployment interface. .env.example documents the required non-SAP variables; its empty values are intentional and it must not replace the deployed file. SAP/TIA, document-router, and BANF service configuration is unchanged.

Non-SAP credentials use Compose's ${VARIABLE:?message} syntax so missing or empty values stop configuration loading. Compose loads the whole project even when a command targets a single service, so provide the complete deployed env file for these commands too. Supplier-managed variables retain their existing behavior.

The root .env supplies YAML interpolation values. Containers receive only variables explicitly listed in their environment sections. Service-level env_file is a different mechanism and does not supply YAML interpolation. See Docker's interpolation documentation.

Preserve literal dollar signs in env-file values using single quotes, for example ADMIN_PW_HASH='$2b$12$example-not-a-real-hash'. Use proper dotenv escaping for embedded quotes; do not shell-source the file. Shell environment variables take precedence over the env file, so run deployment from a controlled environment. Keep actual credentials out of Git and logs. Puppet should restrict file access and disable diffs and plaintext file backups for secrets (show_diff => false, backup => false).

Validate and apply configuration

From the existing deployment directory, validate using the full Puppet-managed environment file. Keep the deployed Compose project name and directory unchanged.

docker compose --env-file .env config --quiet

Use --quiet: plain docker compose config and config --environment can print resolved secrets. Validation checks the Compose model; it does not test database credentials, application behavior, host mounts, or Nginx configuration.

After validation and the database checks below, use a targeted docker compose --env-file .env up -d <service>... during the application's maintenance window. Include its database when its definition changes, and inspect the dependency chain first (the dashboard database depends on the frontend copy job). Avoid a whole-project down/up for these changes. A plain restart does not apply changed container environment variables; see Docker's restart documentation.

Application recreation can change its IP address. The current Nginx upstream configuration resolves static service names at startup/reload. Once the selected application is running, validate and reload the proxy under the existing host deployment procedure, then check the affected site. The proxy is shared with SAP; an Nginx reload affects the shared process even though its configuration is unchanged. See Nginx upstream resolution.

Database readiness and existing data

HedgeDoc now uses separate CMD_DB_* fields so passwords containing URI-special characters are passed literally. Its database receives the same username and password from .env; the previous {{ ... }} expressions were literal strings to Compose. The LDAP search filter's {{username}} is an application placeholder and must remain. See HedgeDoc configuration.

Before applying the HedgeDoc correction to an existing instance, confirm that the actual database role/password match the Hiera values. PostgreSQL's POSTGRES_USER and POSTGRES_PASSWORD initialize an empty data directory; changing them does not update an existing database. Coordinate any required credential change with the application owner and back up the database first. Do not delete or reinitialize the data directory. See the PostgreSQL image documentation.

HedgeDoc and Tomcat Wiki wait for PostgreSQL to accept TCP connections before starting. These pg_isready checks indicate server readiness, not successful application authentication. The dashboard healthcheck authenticates to its configured database and executes SELECT 1, using the existing container environment rather than embedding the password in the healthcheck command. An unhealthy status alone does not automatically restart a container.

HedgeDoc's PostgreSQL 13 image remains a separate migration item. Version 13 is unsupported, and a major upgrade requires a tested backup/restore or pg_upgrade procedure compatible with HedgeDoc. Image versions, data paths, container names, and networks are preserved in this configuration fix. See the PostgreSQL versioning policy.

Follow-up organization

Split Puppet's output into service-specific env files or file secrets before extracting independently operated applications into their own Compose projects. That requires coordinated changes in the Hiera/Puppet repository. Preserve the supplier's SAP/TIA/document-router/BANF definitions; they can later move together into a dedicated directory without changing their configuration style.