Installing Artist Alley

Artist Alley is a single Go binary with the SvelteKit frontend embedded via go:embed. There’s nothing else to deploy — bring your own Postgres and a writable storage directory.

It ships as a multi-arch Docker image (amd64 + arm64), published to both GHCR and Docker Hub from the same commit. Native packages and binaries are a v1.0.0 target — see Other channels.

Quick chooser

Channel	Best for	Pull / install
Docker (GHCR)	Most users — fastest path	docker pull ghcr.io/artist-alley-org/artist-alley:latest
Docker Hub	Same image, alternate registry	docker pull mscrnt/artist-alley:latest
Source	Building from scratch	clone the repo, make build

Docker images are signed via Sigstore (cosign verify — see Verifying signatures).

Prerequisites

• PostgreSQL 14+ — bring your own; Artist Alley creates its own schema on first run via embedded migrations.
• A directory for storage (binary blobs + generated thumbnails) or an S3-compatible bucket (MinIO, Backblaze B2, Cloudflare R2, AWS S3 — all supported via AA_STORAGE_BACKEND=s3).
• A session signing key (AA_SCRAMBLE_KEY) — openssl rand -hex 32.
• An at-rest encryption key (AA_MASTER_KEY) — openssl rand -base64 32. Required at boot; it encrypts federation and per-user keys.

---

Docker (recommended)

docker run -d \
  --name artist-alley \
  -p 8080:8080 \
  -e AA_DB_HOST=postgres.local \
  -e AA_DB_USER=artist_alley \
  -e AA_DB_PASSWORD=secret \
  -e AA_DB_NAME=artist_alley \
  -e AA_SCRAMBLE_KEY=$(openssl rand -hex 32) \
  -e AA_MASTER_KEY=$(openssl rand -base64 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.

Tag fan-out

Tag	Updated when
:vX.Y.Z	exact version (immutable, recommended for prod)
:vX.Y, :vX	latest patch on that line
:latest	most recent stable release
:edge	latest commit on dev (continuous, not stable)
:edge-{sha}	exact dev commit (immutable, pinnable)

Compose example

compose.yaml

services:
  app:
    image: ghcr.io/artist-alley-org/artist-alley:latest
    ports: ["8080:8080"]
    environment:
      AA_DB_HOST: postgres
      AA_DB_USER: artist_alley
      AA_DB_PASSWORD: change-me
      AA_DB_NAME: artist_alley
      AA_SCRAMBLE_KEY: ${SCRAMBLE_KEY}
      AA_MASTER_KEY: ${MASTER_KEY}
    volumes:
      - storage:/var/lib/aa-storage
    depends_on: [postgres]

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: artist_alley
      POSTGRES_USER: artist_alley
      POSTGRES_PASSWORD: change-me
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  storage:
  pgdata:

Building from source

git clone https://github.com/Artist-Alley-Org/artist-alley
cd artist-alley
make build      # produces the single `aa` binary with the SPA embedded

You need a recent Go toolchain and Node/pnpm for the frontend build; make build compiles the SvelteKit SPA and embeds it via go:embed.

---

Other channels (planned)

Releases are Docker-only today. Native distribution — .deb / .rpm packages with a hardened systemd unit, static binaries for Linux/macOS/Windows, and a Homebrew tap — is a v1.0.0 target, tracked in issue #242. Until then, run the Docker image (behind your existing reverse proxy for TLS) or build from source.

---

Verifying signatures

Docker images are keyless-signed via Sigstore:

cosign verify ghcr.io/artist-alley-org/artist-alley:vX.Y.Z \
  --certificate-identity-regexp "https://github.com/Artist-Alley-Org/artist-alley/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

---

Configuration reference

All settings come from environment variables — pass them to the container via -e flags or a compose environment: block (an env_file works too). The table below is generated from docs/install/config/aa.env.example at build time — if you spot a discrepancy with the binary, the env file is the source of truth and a fix belongs there.

HTTP listener

Variable	Default	Notes
AA_HTTP_ADDR	:8080

Postgres

Variable	Default	Notes
AA_DB_HOST	localhost
AA_DB_PORT	5432
AA_DB_NAME	artist_alley
AA_DB_USER	artist_alley
AA_DB_PASSWORD	change-me
AA_DB_SSLMODE	disable

Storage backend

Variable	Default	Notes
AA_STORAGE_BACKEND	fs	fs (default) stores byte blobs under AA_STORAGE_FS_ROOT. s3 uses any S3-compatible API (AWS, MinIO, Backblaze B2, R2, …).
AA_STORAGE_FS_ROOT	/var/lib/artist-alley

Logging

Variable	Default	Notes
AA_LOG_LEVEL	info
AA_LOG_FORMAT	json

Session signing key

Variable	Default	Notes
AA_SCRAMBLE_KEY	change-me-to-32-hex-bytes	Generate with: openssl rand -hex 32

At-rest encryption master key

Variable	Default	Notes
AA_MASTER_KEY	change-me-to-base64-32-bytes	Base64-encoded 32 bytes. Generate with: openssl rand -base64 32 REQUIRED — the service exits at startup without it. Losing this key means losing access to everything it encrypts; back it up.