---
title: Install with Docker
description: Deploy Cuitty on a single VM using Docker Compose. Recommended for solo developers and small teams.
section: Install
order: 1
updatedAt: 2026-04-27
slug: install/docker
---
# 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

```yaml
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:

```bash
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

```bash
docker compose pull portal
docker compose up -d portal
```

The portal runs migrations on startup. Always snapshot first.

## See also

- [Install on Kubernetes](/docs/install/kubernetes)
- [Install on bare metal](/docs/install/bare-metal)
- [Install on cloud providers](/docs/install/cloud)