Skip to content

Environment variables

Start with the Docker quickstart. The downloadable environment template is built directly from the application’s .env.example. Add optional settings to your own .env as needed. Examples below use fictional provider details; replace them with your own values.

Docker Compose reads .env for substitution and forwards only the variables declared in its environment sections. The deployment, mail and S3 settings below are already connected. Advanced runtime overrides need an explicit Compose override; adding them to .env alone does not pass them to the container.

For direct Node execution, ReportHub loads the repository root .env; existing process environment values take precedence. These are application settings, separate from the product website’s configuration.

Variable Default / accepted value Purpose
APP_HOST Required by Compose Public hostname without scheme or path, for example reports.example.org. Used by Caddy and to derive application origins.
CADDY_EMAIL Required by Compose Monitored email address for HTTPS certificate operations.
POSTGRES_PASSWORD Required by Compose Strong database password. Use a generated hex value to avoid URL special characters in the Compose connection string. Do not change it independently on an initialized database.
ANALYTICS_HASH_SECRET Required in production; at least 16 characters Stable random secret for pseudonymizing consent-based application analytics. Generate a separate value from the database password. Does not enable website analytics.
REPORTHUB_TAG latest Container image tag. Pin a tested release for controlled deployments.
TZ Europe/Ljubljana Valid IANA time zone, used by the application and database.
LOG_LEVEL Compose/production: info; direct development: debug Winston log level: error, warn, info, http, verbose, debug or silly.
CORS_ALLOWED_ORIGINS Empty Comma-separated additional browser origins, including scheme and port where relevant. The configured frontend and public API origins are already allowed.
NODE_ENV Docker image: production; direct Node: development Accepts development, test, production. The supplied Compose file uses the image default; a host .env entry does not change the container’s mode.
Variable Default Purpose
MAIL_DELIVERY_ENABLED false Set true to enable delivery defaults. Startup requires SMTP_HOST and SMTP_FROM_EMAIL when this is enabled.
MAIL_DEFAULT_LANGUAGE en Default mail language, en or sl; a recipient’s preferred language can override it.
SMTP_HOST Empty SMTP server hostname.
SMTP_PORT 587 Positive integer; use your provider’s submission port.
SMTP_SECURE false true for TLS from connection start; false permits STARTTLS negotiation. Follow the provider’s requirements.
SMTP_USER Empty Authentication username. If empty, the transport does not send SMTP authentication.
SMTP_PASSWORD Empty Provider password or application password, used with the username.
SMTP_FROM_EMAIL Empty Valid sender email address authorized by your provider.
SMTP_FROM_NAME Empty Optional sender display name.

For a provider using port 587 with STARTTLS:

MAIL_DELIVERY_ENABLED=true
MAIL_DEFAULT_LANGUAGE=en
SMTP_HOST=smtp.example.org
SMTP_PORT=587
SMTP_SECURE=false
SMTP_PASSWORD='replace-with-provider-password'
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME=ReportHub

For implicit TLS on port 465, use SMTP_PORT=465 and SMTP_SECURE=true if required by the provider. Do not disable certificate verification to work around delivery errors.

The application stores mail settings in its configuration. Saved delivery enablement, language, port and TLS settings take precedence over environment defaults. Non-empty saved host and sender settings also take precedence. Credentials always come from SMTP_USER and SMTP_PASSWORD in the environment. On an existing installation, review mail settings in administration after changing .env; demo preparation disables outgoing mail in the saved configuration. Use the application’s mail test to verify delivery before relying on confirmations, invitations or notifications.

STORAGE_TYPE=local is the default. The supplied Compose file persists public branding assets and private report files in the reporthub-files volume, in separate directories.

Variable Default / requirement Purpose
STORAGE_TYPE local Accepts local or s3.
S3_REGION Required for S3 Provider region identifier.
S3_BUCKET Required for S3 Existing bucket name.
S3_ENDPOINT Required for S3 Full service endpoint URL, including https://. Required by the current storage implementation, including for AWS S3.
S3_ACCESS_KEY_ID Required for S3 Access key with the permissions needed to read, write and delete ReportHub objects.
S3_SECRET_ACCESS_KEY Required for S3 Secret matching that access key.
S3_PUBLIC_BASE_URL Optional Public bucket-root URL or CDN equivalent. ReportHub appends /public/<filename>. Without it, public URLs use the endpoint, bucket and public object path.
S3_FORCE_PATH_STYLE true Use false if the provider requires virtual-hosted bucket addressing. This configures the SDK; configure the public base URL to match your public asset endpoint.

Example for an S3-compatible provider:

STORAGE_TYPE=s3
S3_REGION=eu-central-1
S3_BUCKET=reporthub-files
S3_ENDPOINT=https://s3.example.org
S3_ACCESS_KEY_ID=replace-with-access-key
S3_SECRET_ACCESS_KEY='replace-with-secret-key'
S3_PUBLIC_BASE_URL=https://files.example.org/reporthub-files
S3_FORCE_PATH_STYLE=true

One bucket can hold both public/ branding assets and private/ report files. Permit anonymous reads only for public branding assets; deny anonymous bucket listing and direct reads of private files. Report photos, Safety evidence and plans are served through authorized application routes; published Community report photos are available through the public report-image API. Do not make the entire bucket public. The public base URL must point to the bucket root, not its public/ prefix.

Changing storage settings does not move existing files. Plan and verify a file migration before switching an installation with data. Back up both the bucket or local files and the database.

These settings work with direct Node execution. Compose derives the database and origin values and uses image/application defaults for the remaining settings. To customize them in Docker, explicitly set them in reporthub.environment in a Compose override and retain appropriate persistent volumes.

Variable Default Purpose
DATABASE_URL Compose derives the internal PostgreSQL URL; direct Node derives a localhost connection from POSTGRES_PASSWORD Full Prisma PostgreSQL connection URL. Without either value, direct development uses the local postgres credentials. Use explicit secure credentials outside development.
PUBLIC_API_ORIGIN Compose: https://APP_HOST; direct Node: http://localhost:8080 Absolute public API origin for generated API/upload links and the origin allowlist.
FRONTEND_ORIGIN Compose: https://APP_HOST; direct Node: http://localhost:4200 Frontend URL for generated links and allowed browser requests.
TRUST_PROXY true in production, false otherwise Trusts one reverse proxy hop for client IPs. Intended for Caddy; use false for direct serving without a proxy.
UPLOAD_DIR Production: /app/uploads/public; otherwise uploads relative to the backend working directory Local public branding directory. Persist it when overriding the path.
PRIVATE_UPLOAD_DIR Production: /app/uploads/private; otherwise private-uploads relative to the backend working directory Local private files directory; never expose it through a public file server.

The backend port is fixed at 8080. There is no PORT setting. Upload size limits, session lifetime and rate limits are code-defined rather than environment overrides.

Keep .env outside source control and restrict its permissions. Use literal true / false for boolean settings; optional blank provider fields are treated as unset. Single-quote provider secrets containing $ or # to preserve their literal values in Compose’s .env format.

From the installation directory:

Terminal window
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail 100 reporthub

up -d recreates containers when their environment changes; restart alone does not apply new values. Inspect logs privately and redact credentials before sharing them. Avoid publishing the output of docker compose config without --quiet, since it can include resolved secrets. Never remove persistent volumes to apply an environment change.