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.
How settings reach the application
Section titled “How settings reach the application”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.
Deployment and general settings
Section titled “Deployment and general settings”| 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. |
Email and SMTP
Section titled “Email and SMTP”| 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=trueMAIL_DEFAULT_LANGUAGE=enSMTP_HOST=smtp.example.orgSMTP_PORT=587SMTP_SECURE=falseSMTP_PASSWORD='replace-with-provider-password'SMTP_FROM_NAME=ReportHubFor 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.
Local and S3-compatible file storage
Section titled “Local and S3-compatible file storage”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=s3S3_REGION=eu-central-1S3_BUCKET=reporthub-filesS3_ENDPOINT=https://s3.example.orgS3_ACCESS_KEY_ID=replace-with-access-keyS3_SECRET_ACCESS_KEY='replace-with-secret-key'S3_PUBLIC_BASE_URL=https://files.example.org/reporthub-filesS3_FORCE_PATH_STYLE=trueOne 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.
Advanced runtime overrides
Section titled “Advanced runtime overrides”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.
Apply and verify changes
Section titled “Apply and verify changes”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:
docker compose config --quietdocker compose up -ddocker compose psdocker compose logs --tail 100 reporthubup -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.