WebHosting

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

Compose layout

Requires Docker Compose 2.30.0 or later for raw service env files. The root docker-compose.yaml is the deployment entrypoint and assembles these modules:

docker-compose.yaml
stacks/
  proxy/compose.yaml
  legacy-web/compose.yaml
  excalidraw/compose.yaml
  elog/compose.yaml
  pepisco/compose.yaml
  swiss-ecargo/compose.yaml
  hedgedoc/compose.yaml
  opticswiki/compose.yaml
  slsbl/compose.yaml
  n8n/compose.yaml
  dashboard/compose.yaml
  panda-maintenance/compose.yaml
  sap/compose.yaml
  summer-project-selection/compose.yaml
  tomcatwiki/compose.yaml
  scicat-rocrate/compose.yaml
  pikettlischte-beautifier/compose.yaml

Each application stays with its database and supporting containers. legacy-web contains the shared Apache sites and scheduler; elog groups the four logbooks. sap contains the TIA, document-router, and BANF definitions. TIA and document-router keep their existing inline WebUI authentication entries; only the BANF passwords move to separate test and production env files.

Run Compose through the root file, using the existing deployment directory and project name. These modules belong to one Compose project; their shared network definitions remain in the root file. They are not standalone deployment entrypoints. For example, use docker compose --env-file .env up -d excalidraw from the repository root to update that service.

Every include sets project_directory: . so relative paths such as ./apache/conf and the default .env still resolve from the repository root. The service names, container names, images, networks, and data paths are preserved. See Docker's include documentation.

Environment configuration

Swiss eCargo, HedgeDoc, the dashboard, Panda Maintenance, Tomcat Wiki, and BANF read their credentials from service-specific files under /etc/webhosting. In the hiera/data-lx repository, default/lx-docker-01.psi.ch.yaml renders these files from the existing lx-data::docker-env::* keys. Files are root-owned with mode 0600; their directories have mode 0700. Run Compose as a deployment user with permission to read them.

File under /etc/webhosting/	Service	Required non-empty variables
swiss-ecargo/app.env	swiss-ecargo	HOSTED_API_KEY
hedgedoc/app.env	hedgedoc_app	CMD_DB_USERNAME, CMD_DB_PASSWORD, CMD_LDAP_BINDDN, CMD_LDAP_BINDCREDENTIALS, CMD_SESSION_SECRET
hedgedoc/db.env	hedgedoc_db	POSTGRES_USER, POSTGRES_PASSWORD
dashboard/backend.env	it-strategy-dashboard-backend	DB_USER, DB_PASS, JWT_SECRET, ADMIN_PW_HASH
dashboard/db.env	it-strategy-dashboard-db	MYSQL_ROOT_PASSWORD, MYSQL_USER, MYSQL_PASSWORD
panda-maintenance/app.env	panda-maintenance-app	POSTGRES_PASSWORD
panda-maintenance/db.env	panda-maintenance-db	POSTGRES_PASSWORD
tomcatwiki/app.env	tomcatwiki	DB_PASS
tomcatwiki/db.env	tomcatwikidb	POSTGRES_PASSWORD
sap/banf-test.env	banf-fetcher-test	SCP_PASSWORD
sap/banf-prod.env	banf-fetcher-prod	SCP_PASSWORD

The BANF files reuse the existing banf_fetcher_password_test and banf_fetcher_password_prod Hiera keys. The WEBAPP_SECURITY_AUTH_BASIC_USERNAME and WEBAPP_SECURITY_AUTH_BASIC_PASSWORD entries remain inline and unchanged in all four TIA/document-router services.

Each service receives only its own file. Stable nonsecret settings remain in environment:. The files use format: raw: write single-line literal values without adding quotes or doubling dollar signs. Password hashes, quotes, and URI-special characters pass through unchanged. These files are not shell scripts. See Docker's env-file reference.

The optional WEBHOSTING_ENV_DIR variable overrides /etc/webhosting, for example when validating a temporary set of files. .env.example documents this nonsecret setting; it must not replace the production .env.

The existing /opt/WebHosting/.env remains in place for applications outside this repository and rollback, including the old BANF entries. Migrated services no longer reference its old credential variables, including overrides of those variables in the shell. There is no fallback to old credentials if a service env file is missing.

Compose requires all eleven files, including when validating the whole project for a targeted service update. required: true verifies file existence only; it does not enforce the keys or non-empty values listed above. Check those values as part of deployment. This replaces the previous ${VARIABLE:?message} checks for the migrated credentials.

The root .env still supplies YAML interpolation for WEBHOSTING_ENV_DIR. It follows normal dotenv quoting rules; service env_file does not supply interpolation values to YAML. Keep credentials out of Git and logs. See Docker's interpolation documentation.

Validate and apply configuration

Deploy the Hiera change first and let Puppet create all eleven service env files. Verify their permissions and the non-empty keys listed above before activating this Compose change. Preserve the existing global env file for other applications and rollback.

Deploy the complete stacks/ directory alongside the root Compose file. Keep the existing deployment directory and Compose project name. From that directory, validate using the existing global env file and the new service env files:

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

Confirm the host runs Compose 2.30.0 or later and the assembled configuration lists all 31 services before applying it.

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.

The credential source changes, but its values should match the previous configuration. This is not a password rotation or database upgrade. To roll back, restore the previous Compose revision and apply the affected services using the retained global .env. Do not remove that file after this rollout; it still has active consumers.

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 app and database env files derive their shared credentials from the same Hiera keys; 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

After verifying the migration on the host, obsolete migrated entries (including the two BANF passwords) can be removed from the global .env in a separate Hiera change. Preserve values used by applications outside this repository. File secrets and independent Compose projects can be considered separately. Keep the supplier's inline WebUI authentication entries in stacks/sap/compose.yaml unchanged.