Production Compose Installation

This path runs the official Multiforum images behind Caddy with automatic HTTPS on one Linux host. It is a practical production foundation, not a high-availability platform.

Try the local quick-start first. Do not reuse its credentials or local authentication mode in production.

Requirements

• Linux with Docker Engine and Docker Compose v2
• A domain pointed at the host
• TCP ports 80 and 443 and UDP port 443 open to the internet
• An Auth0 Regular Web Application and Auth0 API
• An encrypted off-host backup destination

Prepare the environment

Clone the deployment repository and create a protected production environment:

git clone https://github.com/gennit-project/multiforum-nuxt.git
cd multiforum-nuxt
cp .env.production.example .env.production
chmod 600 .env.production

Generate independent values for the Neo4j password, plugin-secret encryption key, and Auth0 session secret:

openssl rand -hex 32
openssl rand -hex 16
openssl rand -hex 64

Fill every required empty value in .env.production. Pin Neo4j, backend, frontend, and Caddy to tested release or immutable sha-* tags rather than using edge or latest in production.

Optional email, maps, geocoding, and Google Cloud Storage variables can remain empty. Their capabilities will remain unavailable until configured.

Configure Auth0

Create a Regular Web Application, not a Single Page Application, and a dedicated Auth0 API. For forum.example.com, configure:

• Allowed Callback URL: https://forum.example.com/auth/callback
• Allowed Logout URL: https://forum.example.com

Set AUTH0_AUDIENCE to the API identifier. The frontend and backend must use the same Auth0 domain, client ID, and audience. See Auth0 Setup for the complete variable list.

Validate and start

Validate the merged Compose model before creating containers:

docker compose \
  --env-file .env.production \
  -f docker-compose.yml \
  -f docker-compose.production.yml \
  config --quiet

Start the stack and follow its startup logs:

docker compose \
  --env-file .env.production \
  -f docker-compose.yml \
  -f docker-compose.production.yml \
  up -d

docker compose \
  --env-file .env.production \
  -f docker-compose.yml \
  -f docker-compose.production.yml \
  logs --tail=100 caddy frontend backend

Run the read-only production verification:

scripts/verify-self-hosting.sh --env-file .env.production

It confirms that the running containers match the configured images, requires healthy application and database containers, checks Caddy's HTTPS security headers, and sends a harmless query through the public same-origin GraphQL proxy. Complete a real Auth0 login separately.

Persistent state

The production deployment has two application data sets:

• neo4j-data contains the forum database.
• frontend-data contains encrypted Auth0 sessions.

Losing the frontend session volume signs users out. Losing the Neo4j volume loses the forum. Configure backups and recovery before inviting users.

If uploads are enabled, protect the object-storage buckets independently with appropriate retention, versioning, and recovery policies.

Safe upgrades

Prepare a protected target environment without overwriting the known-good file:

cp -p .env.production .env.production.next
$EDITOR .env.production.next

After reviewing release notes and pinning the target images, run:

scripts/upgrade-self-hosting.sh \
  --current-env-file .env.production \
  --target-env-file .env.production.next \
  --backup-output-dir /var/backups/multiforum \
  --confirm-upgrade

The command validates both configurations, pre-pulls the target images, creates a cold safety backup, and force-recreates the stack from the already-pulled images. It blocks Neo4j image changes unless --allow-database-image-change is explicitly supplied.

Verify the target configuration and complete representative reads and writes:

scripts/verify-self-hosting.sh --env-file .env.production.next

Only then promote the environment files:

mv .env.production .env.production.previous
mv .env.production.next .env.production

Retain the previous protected file through the rollback window, then securely remove it because it contains secrets.

Security boundaries and limitations

• Only Caddy should be publicly reachable.
• Keep .env.production, Restic credentials, and backup passwords out of Git, images, and Terraform state.
• Use an external uptime check; same-host monitoring cannot report a dead host.
• The filesystem Auth0 session store supports one frontend replica. Multiple replicas require shared session storage.
• The current foundation does not provide high availability, managed Neo4j, zero-downtime upgrades, or unattended restores.

The deployment repository's production guide is the authoritative command-level reference shipped beside the scripts.