Install

Install with Docker

Deploy Cuitty on a single VM using Docker Compose. Recommended for solo developers and small teams.

HTML Markdown JSON

Install with Docker Compose

Docker Compose is the fastest way to run Cuitty in production-like conditions on a single VM. The reference compose file lives at the root of the cuitty repo.

Reference compose file

version: "3.9"

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: cuitty
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: cuitty
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cuitty"]
      interval: 5s
      timeout: 3s
      retries: 12

  spicedb:
    image: authzed/spicedb:latest
    command: serve --grpc-preshared-key ${SPICEDB_PRESHARED_KEY}
    ports:
      - "50051:50051"

  portal:
    image: ghcr.io/cuitty/portal:latest
    depends_on:
      postgres: { condition: service_healthy }
      spicedb: { condition: service_started }
    ports:
      - "7700:7700"
    environment:
      DATABASE_URL: postgres://cuitty:${POSTGRES_PASSWORD}@postgres:5432/cuitty
      SPICEDB_URL: spicedb:50051
      SPICEDB_TOKEN: ${SPICEDB_PRESHARED_KEY}
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}

volumes:
  pgdata:

Create a .env file with POSTGRES_PASSWORD, SPICEDB_PRESHARED_KEY, and a 32-byte random BETTER_AUTH_SECRET. Then:

docker compose up -d

Backups

The portal stores nothing important on its own filesystem — every byte that matters lives in the postgres and libsql volumes. Snapshot the named volumes nightly with pg_dump and a tar of the libSQL data directory.

Upgrades

docker compose pull portal
docker compose up -d portal

The portal runs migrations on startup. Always snapshot first.

See also