health checks, validation and variable fix.

Signed-off-by: Basil Bruhn <basil.bruhn@psi.ch>

README.md

@@ -0,0 +1,93 @@
+# 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](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/).
+
+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.
+
+```sh
+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](https://docs.docker.com/reference/cli/docker/compose/restart/).
+
+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](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve).
+
+## 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](https://docs.hedgedoc.org/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](https://hub.docker.com/_/postgres).
+
+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](https://www.postgresql.org/support/versioning/).
+
+## 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.