Server Configuration Reference

Multiforum configuration has two layers:

1. Environment variables describe deployment capabilities, credentials, image versions, and public URLs.
2. ServerConfig and related role nodes contain administrator-controlled forum settings.

Use .env.quickstart.example for local evaluation and .env.production.example with the production Compose overlay. The examples in the deployment repository are authoritative and are validated in CI.

Automatic setup

When the database is empty, the backend creates ServerConfig, default roles, and the initial administrator relationship. Manual Cypher initialization is no longer required for the supported Compose paths.

The quick-start uses:

MULTIFORUM_AUTH_PROVIDER=local-dev
MULTIFORUM_BOOTSTRAP_EMAIL=admin@multiforum.local
MULTIFORUM_BOOTSTRAP_USERNAME=admin
MULTIFORUM_BOOTSTRAP_PASSWORD=multiforum-local-admin

Production uses Auth0 and MULTIFORUM_SUPERADMIN_EMAIL. Local bootstrap password authentication must never be exposed publicly.

Production deployment variables

Instance and network

Variable	Description
MULTIFORUM_DOMAIN	Public hostname without scheme or path
MULTIFORUM_INSTANCE_NAME	User-facing instance name
MULTIFORUM_BIND_ADDRESS	Host address for diagnostic ports; production defaults to loopback
CADDY_ACME_EMAIL	ACME contact used by Caddy

Pinned images

Variable	Description
MULTIFORUM_NEO4J_IMAGE	Tested Neo4j image reference
MULTIFORUM_BACKEND_IMAGE	Official backend image reference
MULTIFORUM_BACKEND_PULL_POLICY	Compose pull policy
MULTIFORUM_FRONTEND_IMAGE	Official frontend image reference
MULTIFORUM_FRONTEND_PULL_POLICY	Compose pull policy
MULTIFORUM_CADDY_IMAGE	Tested Caddy image reference

Use release or immutable sha-* tags in production rather than edge or latest.

Required secrets and identity

Variable	Description
NEO4J_PASSWORD	Neo4j password
MULTIFORUM_SUPERADMIN_EMAIL	Verified Auth0 break-glass administrator email
PLUGIN_SECRET_ENCRYPTION_KEY	32-character key used to protect plugin secrets
AUTH0_DOMAIN	Auth0 tenant domain
AUTH0_CLIENT_ID	Auth0 Regular Web Application client ID
AUTH0_AUDIENCE	Auth0 API identifier
NUXT_AUTH0_CLIENT_SECRET	Auth0 Regular Web Application client secret
NUXT_AUTH0_SESSION_SECRET	Long secret protecting frontend sessions

The production overlay derives the frontend base URL, logout URL, callback base, and GraphQL proxy configuration from MULTIFORUM_DOMAIN. Do not recreate the former VITE_AUTH0_* or VITE_GRAPHQL_URL configuration.

Optional object storage

Variable	Description
GCS_BUCKET_NAME	Public image/upload bucket
GCS_PRIVATE_DOWNLOAD_BUCKET_NAME	Private downloadable-file bucket
GOOGLE_CREDENTIALS_BASE64	Base64 service-account JSON

If these remain empty, upload capabilities remain disabled.

Optional maps and geocoding

Variable	Description
GOOGLE_MAPS_API_KEY	Browser-restricted Google Maps key
GOOGLE_MAP_ID	Optional Google Map ID
OPEN_CAGE_API_KEY	OpenCage geocoding key

The production image receives these values at runtime through NUXT_PUBLIC_* runtime configuration. Rebuilding the frontend is not required.

Optional email

Variable	Description
EMAIL_PROVIDER	resend or sendgrid
EMAIL_FROM	Sender address
RESEND_API_KEY	Resend API key
SENDGRID_API_KEY	SendGrid API key
SENDGRID_FROM_EMAIL	Optional SendGrid-specific sender address

Email gracefully no-ops when it is unconfigured.

Capability status

The backend reports setup state for authentication, email, maps, geocoding, uploads, downloads, events, and plugins. Each capability can distinguish configured from enabled and report missing required variables. The frontend uses this as the source of truth for Admin → Instance Setup and feature placeholders.

ServerConfig fields

Basic information

Field	Type	Description
serverName	String	Instance identifier/name
serverDescription	String	Public description
serverIconURL	String	Server icon URL
rules	JSON	Server-wide rules

Feature toggles

Field	Type	Description
enableDownloads	Boolean	Allow download features when storage is configured
enableEvents	Boolean	Allow event features
allowedFileTypes	[String]	Server-level allowed file extensions

Plugins

Field	Type	Description
pluginRegistries	[String]	Plugin registry endpoints
pluginPipelines	JSON	Ordered event pipeline configuration

Installed plugin versions, administrators, moderators, suspensions, invitations, and default roles are represented through relationships from ServerConfig.

Default roles

First-run setup creates default user, moderator, elevated moderator, suspended user, and suspended moderator roles. Administrators can review their detailed permissions under Admin → Roles. See the Admin Settings Reference for the permissions and membership workflow.

Validate configuration

Before a production start or upgrade:

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

Compose rejects empty required production values. After startup, run:

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