Sign up

Self-Hosted Installation Guide

Open inAnthropic

This guide covers three ways to run TerminusDB on your own infrastructure, from simplest to most customisable. For a quick local setup, see the quickstart. This page is for production or shared-team deployments.

Option 1: Docker (single container)

The quickest path to a production-ready instance. A single Docker command with persistent storage:

Example: Bash
docker run -d \
  --name terminusdb \
  --restart unless-stopped \
  -p 127.0.0.1:6363:6363 \
  -v terminusdb_storage:/app/terminusdb/storage \
  -e TERMINUSDB_SERVER_PORT=6363 \
  -e TERMINUSDB_AUTOLOGIN=false \
  terminusdb/terminusdb-server:v12

Production flags explained

FlagPurpose
--restart unless-stoppedAutomatically restart on crash or host reboot
-p 127.0.0.1:6363:6363Bind to localhost only — put a reverse proxy in front for external access
-v terminusdb_storage:/app/terminusdb/storageNamed volume for data persistence across container recreations
-e TERMINUSDB_AUTOLOGIN=falseDisable auto-login — require password for all connections

Change the default password

After first start, change the admin password immediately:

curl -s -u admin:root -X PUT http://localhost:6363/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "admin", "password": "your-secure-password"}'

Expose to the network

To make the instance accessible to other machines, bind to 0.0.0.0 and place a TLS reverse proxy (nginx, Caddy, or Traefik) in front:

Example: Bash
docker run -d \
  --name terminusdb \
  --restart unless-stopped \
  -p 0.0.0.0:6363:6363 \
  -v terminusdb_storage:/app/terminusdb/storage \
  -e TERMINUSDB_AUTOLOGIN=false \
  terminusdb/terminusdb-server:v12

Always use TLS

TerminusDB transmits credentials as Basic Auth headers. Without TLS, passwords are sent in cleartext. Always put a reverse proxy with TLS termination in front of TerminusDB when exposing it to a network.

Option 2: Docker Compose

For teams that want a reproducible setup or need to run TerminusDB alongside other services:

Example: YAML
# docker-compose.yml
services:
  terminusdb:
    image: terminusdb/terminusdb-server:v12
    container_name: terminusdb
    restart: unless-stopped
    ports:
      - "127.0.0.1:6363:6363"
    volumes:
      - terminusdb_data:/app/terminusdb/storage
    environment:
      TERMINUSDB_SERVER_PORT: "6363"
      TERMINUSDB_AUTOLOGIN: "false"
      TERMINUSDB_ENABLE_DASHBOARD: "false"

volumes:
  terminusdb_data:
    driver: local

Start with:

Example: Bash
docker compose up -d

Adding a reverse proxy

Extend the compose file with Caddy for automatic TLS:

Example: YAML
services:
  terminusdb:
    image: terminusdb/terminusdb-server:v12
    restart: unless-stopped
    volumes:
      - terminusdb_data:/app/terminusdb/storage
    environment:
      TERMINUSDB_SERVER_PORT: "6363"
      TERMINUSDB_AUTOLOGIN: "false"

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    depends_on:
      - terminusdb

volumes:
  terminusdb_data:
  caddy_data:

With a Caddyfile:

Example: Text
terminusdb.example.com {
    reverse_proxy terminusdb:6363
}

Option 3: Bare metal / binary

TerminusDB can run directly on a host without Docker.

Download the binary

Pre-built binaries are available from GitHub Releases. Download the binary for your platform:

# Linux x86_64
curl -L -o terminusdb \
  https://github.com/terminusdb/terminusdb/releases/latest/download/terminusdb-amd64-linux

chmod +x terminusdb

Run the server

Example: Bash
export TERMINUSDB_SERVER_DB_PATH="./storage"
export TERMINUSDB_SERVER_PORT=6363
export TERMINUSDB_AUTOLOGIN=false

./terminusdb serve

The server stores all data in the path specified by TERMINUSDB_SERVER_DB_PATH. Back up this directory for disaster recovery.

Supported platforms

PlatformArchitectureStatus
Linuxx86_64, arm64Fully supported
macOSx86_64, arm64 (Apple Silicon)Fully supported
Windowsx86_64Via WSL2 or Docker

Build from source

For custom builds or unsupported platforms, see Build from Source.

Environment Variables

Key configuration variables for production deployments:

VariableDefaultDescription
TERMINUSDB_SERVER_PORT6363HTTP port the server listens on
TERMINUSDB_SERVER_NAME127.0.0.1Bind address
TERMINUSDB_SERVER_WORKERS8Number of worker threads
TERMINUSDB_SERVER_DB_PATH./storage/dbData storage location
TERMINUSDB_AUTOLOGINtrueSkip auth for local access (disable in production)
TERMINUSDB_JWT_ENABLEDfalseEnable JWT authentication
TERMINUSDB_ENABLE_DASHBOARDtrueServe the web dashboard UI
TERMINUSDB_SERVER_MAX_TRANSACTION_RETRIES3Max retry count for conflicting transactions

Health checks

Use the /api/ok endpoint for load balancer health checks:

curl -s http://localhost:6363/api/ok
# Returns: "ok"

For a more detailed check that includes authentication:

curl -s -u admin:root http://localhost:6363/api/info

Backups

TerminusDB provides two approaches for backup: the CLI bundle commands for community use, and enterprise-grade backup tooling for production deployments.

CLI bundle and unbundle

The TerminusDB CLI includes db bundle and db unbundle commands for creating portable backups of individual databases:

Example: Bash
# Create a bundle backup
terminusdb db bundle admin/MyDatabase --output MyDatabase-backup.bundle

# Restore from a bundle
terminusdb db unbundle admin/MyDatabase MyDatabase-backup.bundle

Bundles capture all commits, branches, and data as a single file. They can be transferred between TerminusDB instances of the same version.

Storage volume backup

For a full instance backup (all databases), stop the container and archive the storage volume:

Example: Bash
docker compose stop terminusdb
tar -czf terminusdb-backup-$(date +%Y%m%d).tar.gz \
  $(docker volume inspect terminusdb_data --format '{{.Mountpoint}}')
docker compose start terminusdb

Enterprise backup tooling

For production deployments with automated scheduling, point-in-time recovery, incremental backups, and cross-instance replication, see the Enterprise Backup and Restore documentation.

Next steps

Open inAnthropic
Report issue

Was this helpful?