logo
Install and configureDocker
Install and configure

Run SlugBase with Docker

Build and run the production Docker image: ports, volumes, health checks, and build-time frontend options.

What you need

  • Docker installed on your server or workstation.
  • Strong values for JWT_SECRET, ENCRYPTION_KEY, and (for production) SESSION_SECRET — see Configuration.
  • A host directory you can mount for SQLite data (default database path inside the container is /app/data/slugbase.db).

The primary Dockerfile at the repository root produces a single container that runs the Node backend and serves the built frontend static assets from public in production mode.

Do not paste real secrets into issue trackers or chat logs. Use a secret store, .env (kept out of git), or your orchestrator’s secret mechanism.

Steps

Prepare environment variables

Create a file (for example .env) or export variables in your shell. At minimum you need the secrets the server validates at startup. When the app is reachable on a public URL, also set BASE_URL and FRONTEND_URL to that HTTPS origin. See Configuration for details.

Build the image

From the repository root (where the Dockerfile lives):

docker build -t slugbase:local .

Optional build arguments (defaults are for self-hosted):

  • VITE_SLUGBASE_MODE — defaults to selfhosted (use cloud only for SaaS-style builds).
  • VITE_API_URL — usually empty for same-origin self-hosted.
  • VITE_SENTRY_DSN / VITE_SENTRY_DEBUG — optional error reporting.

Run the container

Map port 5000, persist /app/data, and pass environment variables (example uses --env-file):

mkdir -p ./data
docker run -d \
  --name slugbase \
  -p 5000:5000 \
  -v "$(pwd)/data:/app/data" \
  --env-file .env \
  -e DB_PATH=/app/data/slugbase.db \
  slugbase:local

The image sets NODE_ENV=production, PORT=5000, and defaults DB_TYPE=sqlite with DB_PATH=/app/data/slugbase.db.

Verify

  • Health: The Dockerfile defines a health check that expects HTTP 200 from http://localhost:5000/api/health inside the container.
  • UI: Open http://localhost:5000 (or your mapped host/port). On a fresh database you should see Initial Setup — see First run setup.
  • API docs: OpenAPI is served at /openapi.json and /openapi.yaml; Swagger UI is at /api-docs unless you set SLUGBASE_API_DOCS=false (disables the UI only).

Backend-only image

For API-only deployments (no bundled SPA), the repository ships Dockerfile.backend. It builds only the backend workspace, exposes PORT defaulting to 8080 in the image environment, and uses the same /api/health check pattern. Typical users who want the full bookmark UI should use the main Dockerfile instead.

Troubleshooting

Docker Compose

Declarative service, env file, and optional Postgres sidecar.

Reverse proxy

TLS termination and headers in front of the container.

Was this page helpful?

Last updated 3 days ago

Built with Documentation.AI