# 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.