Install and configure

Configuration

Environment variables and secrets for self-hosted SlugBase: database, server URLs, security, registrations, and API docs.

What you need

Access to the environment where the Node process runs (.env, systemd, Kubernetes secrets, or Compose env_file).
Cryptographically strong random values for secrets (the server enforces minimum lengths for several of them).

The backend reads configuration from the process environment. Defaults apply for development; security validation runs at startup and exits the process if requirements are not met.

Security and session variables

These are validated before the server starts listening for connections:

Variable	Requirement
`JWT_SECRET`	Required. At least 32 characters and not the documented default placeholder string.
`ENCRYPTION_KEY`	Required. At least 32 characters.
`SESSION_SECRET`	In `NODE_ENV=production`, required with length at least 32. (In development, missing values may warn.)

Generate values with Node, for example:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Run twice for separate JWT_SECRET and ENCRYPTION_KEY values.

Server and URLs

Variable	Role
`PORT`	HTTP listen port (default 5000).
`NODE_ENV`	`development` or `production`. Production enables stricter session handling and static SPA serving.
`BASE_URL`	Public base URL of the app (used for redirects and cookie security logic). Default in code: `http://localhost:5000`. Set to your real HTTPS URL in production.
`FRONTEND_URL`	Origin allowed for CORS and related checks. Default: `http://localhost:3000`. For the bundled self-hosted UI on the same origin, set this to the same public URL as `BASE_URL`.
`CORS_EXTRA_ORIGINS`	Comma-separated extra allowed origins when needed.

Session cookies use secure: true when NODE_ENV=production and BASE_URL starts with https://, so HTTPS deployments should set BASE_URL to an https:// URL.

Database

Variable	When
`DB_TYPE`	`sqlite` (default) or `postgresql`.
`DB_PATH`	SQLite file path (Dockerfile default `/app/data/slugbase.db`).
`DATABASE_URL`	PostgreSQL connection string (alternative to discrete fields).
`DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`	Used when `DB_TYPE=postgresql` and `DATABASE_URL` is not set.

The application runs migrations automatically on startup.

Self-hosted mode and registrations

Variable	Role
`SLUGBASE_MODE`	Omit or set to `selfhosted` for normal self-hosted behavior. (`cloud` is for the hosted product stack only.)
`REGISTRATIONS_ENABLED`	If set to the string `false`, new user registration is disabled. Otherwise registrations remain enabled (default).

For self-hosted deployments, SMTP is configured in the app under Admin → Settings, not via Postmark env vars. The open-source backend does not read CONTACT_FORM_RECIPIENT and does not ship a contact-form HTTP route (for example /api/contact); that variable is only relevant to SlugBase Cloud’s marketing contact flow, not to self-hosted installs.

AI suggestions (self-hosted)

Self-hosted installs configure OpenAI for bookmark suggestions in Admin → AI Suggestions in the UI (not via AI_OPENAI_* env vars, which are documented for cloud-style deployments in the README).

API documentation toggle

Variable	Effect
`SLUGBASE_API_DOCS`	Set to `false` to disable the Swagger UI at `/api-docs`. OpenAPI JSON/YAML routes remain available unless separately restricted.

Troubleshooting

Reverse proxy

TLS, BASE_URL, and proxy hop configuration.

Docker Compose

Mounting .env and data volumes.

Was this page helpful?

Last updated 2 days ago

Built with Documentation.AI