Quickstart

This guide gets a complete Alcoves instance running locally: the Nuxt frontend, the Go API + worker, PostgreSQL, and Dragonfly (a Redis-compatible queue).

Sample doc

This is a starter quickstart. Commands mirror the repo’s deployment & operations guide — check there for the authoritative, full reference.

Prerequisites

• Docker and Docker Compose (v2)
• ~8 GB of free RAM (the CPU-only ML models are the ceiling)
• Git

1. Clone and configure

git clone https://github.com/rustyguts/alcoves.git
cd alcoves
cp .env.example .env

Open .env and set a real session secret before anything else:

# Generate an AES-GCM key (must be ≥ 32 bytes)
openssl rand -base64 32

Paste the result into ALCOVES_SESSION_SECRET.

2. Start the stack

docker compose up

This brings up four services:

Service	Host port	Purpose
Frontend	3000	Nuxt (Nitro) server — open this in your browser
Backend API	3001	Go API + worker (ALCOVES_MODE=all)
Dragonfly	6389	Redis-compatible async job queue (Asynq)
PostgreSQL	internal	Primary database; reachable in-network at postgres:5432 only

Note

PostgreSQL is not published to the host by the default docker-compose.yml — it’s only reachable from the other containers (at postgres:5432). If you want to connect from your machine, add a ports: mapping to the postgres service.

Goose migrations run automatically on startup, so the schema is ready the first time the API boots.

3. Open the app

Visit http://localhost:3000 and register the first account. The first user becomes the instance owner — the only role that can reach the admin panel, the job queue dashboard, registration policy, and ML-model selection.

Tip

The AI features (faces, objects, audio events, transcription) run asynchronously. Upload a few photos or a short video, then watch the job queue in the admin panel work through detection — no GPU required.

4. Infrastructure only (optional)

To run Postgres and Dragonfly in Docker but the apps from source:

docker compose up -d postgres dragonfly

Then start each side from its own directory:

# Backend (from backend/)
go run cmd/server/main.go

# Frontend (from frontend/)
bun install
bun run dev

Next steps

• Configuration — every ALCOVES_* knob.
• Architecture overview — how the pieces fit together.
• Privacy & local AI — how inference stays on your box.