Compose / Environment variables
=================================

This document lists environment variables that can be provided to the
`docker-compose` file to customize runtime behaviour. All variables below
have safe defaults (either defined by the Compose file itself or by code)
so the container can start without an explicit `.env` file. Override any
value in your own `.env` when necessary.

Note: most variables are documented in `.env.example` as well. This file
focuses on the variables that are referenced in `docker-compose.yml`.

Variables
---------

ROOT_PASSWORD
~~~~~~~~~~~~~
- **Purpose**: Root password used by the Web Desktop (Selkies/VNC) process.
- **Default**: "password" (compose fallback)
- **Recommendation**: Change in production deployments; safe to omit in dev.
 
.. note::

	This project keeps `ROOT_PASSWORD` explicitly present in the `environment:`
	block of `docker-compose.yml` to make it obvious for operators that the
	Web Desktop root credential exists and should be set in production. Even
	if you omit it, the compose fallback will apply the default value.

DISPLAY_WIDTH, DISPLAY_HEIGHT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Purpose**: Virtual display resolution for Selkies / Web Desktop.
- **Default**: 1280x720
- **Recommendation**: Leave defaults for local dev; set to higher values if you need a larger remote desktop.

SYNTH_X11_WAIT_SECONDS
~~~~~~~~~~~~~~~~~~~~~~
- **Purpose**: Number of seconds the container will wait for the X11 socket (`/tmp/.X11-unix/X1`) before continuing startup.
- **Default**: 30
- **Recommendation**: Leave at default for most setups. Lower to `0` for headless-only deployments or increase if your host X server takes longer to appear.

SYNTH_CREATE_X11_PLACEHOLDER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Purpose**: When set to `1` (default) the container will create a placeholder file at `/tmp/.X11-unix/X1` after the timeout so startup can continue even if the host X socket isn't mounted. Set to `0` to make the container proceed without creating the placeholder (fail-fast behavior).
- **Default**: `1`
- **Recommendation**: Keep `1` to avoid the container blocking in environments where a host X socket isn't present; set to `0` if you require the container to fail early when X is missing.

SYNTH_WEBUI_HTTP_PORT, SYNTH_WEBUI_HTTPS_PORT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Purpose**: Ports used by the Synthetic Heart Web UI (HTTP/HTTPS).
- **Default**: HTTP 8001, HTTPS 8000 (compose fallback); web UI has additional internal defaults in code.
- **Recommendation**: Keep defaults locally; set explicit values in multi-service hosts or when port conflicts exist.

SYNTH_WEBUI_HOST
~~~~~~~~~~~~~~~~
- **Purpose**: Host binding for the web UI server (e.g. 0.0.0.0).
- **Default**: 0.0.0.0
- **Recommendation**: Keep default unless you want to restrict listening to localhost.

SECURE_CONNECTION / SYNTH_WEBUI_TLS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Purpose**: Toggle TLS/HTTPS for Selkies and/or the Web UI.
- **Default**: TLS enabled in dev for the Web UI (see `.env.example`).
- **Recommendation**: Keep TLS enabled in production; for local development a self-signed certificate is generated if no cert is provided.

**Default behaviour details**

- **SYNTH_WEBUI_TLS**: If not set, the application falls back to enabling TLS by default (value `1`) to provide a secure developer experience. You only need to set this to `0` when you explicitly want to disable HTTPS.
- **SYNTH_WEBUI_CERT_DIR**: If no certificate/key are provided, the Web UI will look for certificates in `/config/ssl` and, if missing, will attempt to generate a self-signed certificate there at startup.
- **SYNTH_ATTACHMENTS_ROOT**: Optional root directory for Web UI attachments. If set, uploaded files are stored there. If unset, the application will use `$XDG_DATA_HOME/attachments` when `XDG_DATA_HOME` is defined, otherwise `/config/uploads`.
- **Image seed**: The container image ships a default self-signed certificate and key in `/config/ssl` (copied from `/app/res/default_ssl`) so HTTPS works out-of-the-box unless a volume overwrites that path.

DB_HOST
~~~~~~~
- **Purpose**: Hostname of the MariaDB service used by the application.
- **Default**: `synth-db` (compose fallback)
- **Recommendation**: For multi-container setups keep `synth-db` or set this to an external host if you run the DB elsewhere.

DB_AUTO_HEAL
~~~~~~~~~~~~
- **Purpose**: When enabled, the DB layer will attempt an automatic, idempotent "schema heal" if a query fails with a missing table/column error (e.g. error 1146 / 1054). The heal runs core/plugin table-ensurers and retries the failed statement once.
- **Default**: `1` (enabled)
- **Recommendation**: Leave enabled for development and restore/upgrade resilience; set to `0` to disable automatic repairs in locked-down production environments where implicit schema changes are undesired.

CLI_SERVER_PORT
~~~~~~~~~~~~~~~
- **Purpose**: Port mapping for an internal CLI server used by tooling and integrations.
- **Default**: 5555 (compose fallback; can be overridden in `.env`)
- **Recommendation**: Typically safe to leave at default for local dev.

Why these were removed from explicit compose environment list
-----------------------------------------------------------
Each variable above has been removed from the `environment:` block in
`docker-compose.yml` to avoid duplicating values that already have sensible
fallbacks in Compose (`${VAR:-fallback}`) or in the application code.
Keeping them documented here ensures maintainers know what can be set if
customisation is required.

Best Practices
--------------
- Keep a `.env` (not checked into git) for environment-specific overrides.
- Use `.env.example` to show recommended/default values for contributors.
- Lock down passwords and TLS certs in production and avoid using defaults.

If you want, I can move these entries back into `docker-compose.yml` with
clear comments and a link to this document, or add CI checks that validate
expected ports are reachable after a compose up.