Docker

Docker is the quickest way to deploy Opengram. A single command gives you a running instance with automatic database migrations and a built-in health check.

Quick start

docker run -d \
  --name opengram \
  --restart unless-stopped \
  -p 3000:3000 \
  -v opengram_data:/opt/opengram/data \
  -v "$(pwd)/config:/opt/opengram/config" \
  opengram/web:latest

This starts Opengram on port 3000 with persistent storage for both the database and your configuration file. The --restart unless-stopped flag ensures the container restarts automatically after a reboot.

Environment variables

The container uses the following environment variables by default:

You can override any of these with -e:

docker run -d \
  --name opengram \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PORT=8080 \
  -v opengram_data:/opt/opengram/data \
  opengram/web:latest

See the Environment Variables reference for the full list, including server overrides, rate limiting, and API keys.

Data persistence

Mount /opt/opengram/data to persist the SQLite database and uploaded files across container restarts:

-v opengram_data:/opt/opengram/data

This volume contains:

• opengram.db -- the SQLite database with all chats, messages, and metadata
• uploads/ -- uploaded files and media attachments

Back up this volume to preserve all Opengram data. See Backup & Restore for instructions.

Config mounting

The image ships with a default opengram.config.json. To customize it, create your own config file locally and mount it into the container:

-v "$(pwd)/config:/opt/opengram/config"

See Configuration for the full list of options.

Resource recommendations

Opengram is lightweight:

• Memory: 256--384 MB is sufficient for most workloads
• CPU: A single core handles typical usage

You can set resource limits in Docker:

docker run -d --name opengram \
  --restart unless-stopped \
  --memory=384m \
  -p 3000:3000 \
  -v opengram_data:/opt/opengram/data \
  opengram/web:latest

Health check

The image includes a built-in health check that polls GET /api/v1/health every 30 seconds with a 5-second timeout, a 20-second start period, and 3 retries. Container orchestrators like Docker Compose and Kubernetes will automatically use this to determine container health.

Entrypoint and migrations

The container entrypoint runs database migrations before starting the server. This means you can safely upgrade to a new image version and migrations will apply automatically on the next startup. See Upgrading for more details.

Docker Compose

For a more maintainable setup, use Docker Compose:

services:
  opengram:
    image: opengram/web:latest
    container_name: opengram
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - opengram_data:/opt/opengram/data
      - ./config:/opt/opengram/config
    environment:
      - OPENGRAM_TRUST_PROXY_HEADERS=true  # set to true if behind a reverse proxy
    # env_file:
    #   - ./opengram.env  # alternative: load env vars from a file

volumes:
  opengram_data:

Start the service:

docker compose up -d

View logs:

docker compose logs -f opengram