forked from linux/WebHosting
94 lines
5.3 KiB
Markdown
94 lines
5.3 KiB
Markdown
# 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.
|