Getting started

Artist Alley is a single Go binary with the SvelteKit frontend embedded. There are three common starting points; pick the one that matches what you’re doing.

I want to try it

The quickest way is the published Docker image. Point it at a Postgres (your own, or one in the same compose stack). Two keys are generated here and must stay stable across restarts — AA_MASTER_KEY wraps at-rest crypto and the server refuses to boot without it, AA_SCRAMBLE_KEY is the password-hashing pepper:

docker run -d --name artist-alley \
  -p 8080:8080 \
  -e AA_DB_HOST=postgres.local \
  -e AA_DB_PASSWORD=secret \
  -e AA_MASTER_KEY=$(openssl rand -base64 32) \
  -e AA_SCRAMBLE_KEY=$(openssl rand -hex 32) \
  -v artist-alley-storage:/var/lib/aa-storage \
  ghcr.io/artist-alley-org/artist-alley:latest

Open http://localhost:8080 and walk through first-run setup. The Docker Compose setup (and building from source) lives in the Install guide.

I want to install it for a team

Read the Install guide — run the published Docker image behind your existing reverse proxy for TLS. Distribution is Docker-only today; native packages (.deb/.rpm, Homebrew) are a v1.0.0 roadmap item. The For operators guide covers Postgres setup, storage backends (filesystem or any S3-compatible bucket), backups, and updates.

I want to hack on the code

Local development uses Docker Compose, so the stack you run locally is the same one CI exercises.

Prerequisites

• Docker + Docker Compose
• ~10 GB of disk for Postgres + a starter filestore
• A free TCP port for the web UI (default 8080)

Boot the stack

git clone git@github.com:artist-alley-org/artist-alley.git
cd artist-alley
cp .env.example .env
docker compose up -d --build

The Vite dev server (with hot reload) runs on :5173; the Go server talks to it through nginx on :8080. Edit Svelte files in web/src/ and they hot-reload; edit Go files and run docker compose up -d --build to rebuild the app container.

Verifying the stack

# Postgres ready:
docker compose exec -T postgres pg_isready -U artist_alley -d artist_alley

# Hit the Go health endpoint:
curl -s http://localhost:8080/healthz

# Run the integration tests:
./scripts/test.sh

The same ./scripts/test.sh runs in CI — see .github/workflows/ci.yml.

What to read next

• API reference — every endpoint with request / response shapes.
• Architecture — how the binary, database, and frontend fit together.
• Architecture Decisions — the reasoning behind the big calls.