Server Configuration Reference
Multiforum configuration has two layers:
- Environment variables describe deployment capabilities, credentials, image versions, and public URLs.
ServerConfigand 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 branding
| Variable | Description |
|---|---|
NUXT_PUBLIC_BRANDING_PRODUCT_NAME | Name in the footer attribution |
NUXT_PUBLIC_BRANDING_DOCS_URL | Documentation link target |
NUXT_PUBLIC_BRANDING_SOURCE_URL | Source repository link target |
NUXT_PUBLIC_BRANDING_ISSUES_URL | Issue tracker link target |
NUXT_PUBLIC_BRANDING_SUPPORT_EMAIL | Support contact address |
NUXT_PUBLIC_BRANDING_SHOW_UPSTREAM_LINKS | false hides all upstream references |
NUXT_PUBLIC_BRANDING_CUSTOM_FOOTER_LINKS | JSON array of {label, url} footer links |
NUXT_PUBLIC_BRANDING_LOCKED | true pins branding to these variables and makes the admin tab read-only |
These are optional; administrators can set the same values under Admin Settings → Settings → Branding. Each one is passed to the frontend container only when it is set, so an unset variable keeps the built-in default while an assigned empty value deliberately hides that link. See Instance branding.
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 |
Branding
| Field | Type | Description |
|---|---|---|
brandingProductName | String | Name in the footer attribution |
brandingDocsURL | String | Documentation link target |
brandingSourceURL | String | Source repository link target |
brandingIssuesURL | String | Issue tracker for the software itself |
brandingSupportEmail | String | Support contact address for this instance |
brandingShowUpstreamLinks | Boolean | Show documentation, source and attribution links (default true) |
brandingCustomFooterLinks | JSON | Array of {label, url} footer links, at most eight |
The following fields exist on ServerConfig but are not rendered yet:
brandingLogoDarkURL, brandingLogoAlt, brandingFaviconURL, and
brandingPrimaryColor. serverIconURL doubles as the light-mode logo.
Branding fields are writable only by administrators and are validated on save:
URLs must be http(s) or site-relative, so a javascript: or data: URL
cannot be stored and later rendered into a link. An empty string clears a field;
see Instance branding for the full resolution order
and the NUXT_PUBLIC_BRANDING_* variables that can set or pin these values.
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.
Server plugin state can also be reconciled from a versioned desired-state manifest. See Declarative plugin configuration.
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