Installing Artist Alley
Artist Alley ships as a Docker image: one Go binary with the SvelteKit
frontend embedded via go:embed, packaged together with the runtime tools
it calls. Bring your own Postgres and a writable storage directory or
S3-compatible bucket. Artist Alley is pre-1.0 and in active development,
so features are still landing and it isn’t production-ready yet.
Release images are multi-arch (amd64 + arm64) and are published to
both GHCR and Docker Hub from the same build; the continuous :edge
images are amd64 only. Native packages and binaries are planned; see
Other channels.
Quick chooser
Section titled “Quick chooser”In the pull commands, X.Y.Z is the release version you choose from the
releases page, without the leading v.
| Channel | Best for | Pull / install |
|---|---|---|
| Docker (GHCR) | Most users, fastest path | docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z |
| Docker Hub | Same image, alternate registry | docker pull mscrnt/artist-alley:X.Y.Z |
| Source | Building the image yourself | clone the repo, docker build (see Building from source) |
Release images are signed via Sigstore, and :edge images are not (cosign verify, see
Verifying signatures).
Prerequisites
Section titled “Prerequisites”- Docker to run the image, and OpenSSL to generate the keys below.
- PostgreSQL 15 or newer, with the pgvector extension (0.5.0 or
newer). Bring your own; Artist Alley creates its own schema on first
run via embedded migrations. Those migrations also enable
pg_trgm,pgcryptoanduuid-ossp, which ship with standard Postgres, but pgvector is installed separately. The simplest route is apgvector/pgvectorimage in place of plainpostgres, as in the compose example below. The database role Artist Alley connects as must be a superuser; see For operators. - 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 password-hashing pepper (
AA_SCRAMBLE_KEY):openssl rand -hex 32. Keep it stable across restarts and container replacements; a new one stops every existing password from working. - An at-rest encryption key (
AA_MASTER_KEY):openssl rand -base64 32. Required at boot; it encrypts federation and per-user keys, and losing it means losing everything it encrypted.
Generate both keys once, store them somewhere safe, and reuse them every time you restart or replace the container. A restorable install is the database, the stored files and both keys together (Backup).
Docker (recommended)
Section titled “Docker (recommended)”Write the two keys to a file once:
# Run this once, then keep artist-alley.env somewhere safe.umask 077cat > artist-alley.env <<EOFAA_MASTER_KEY=$(openssl rand -base64 32)AA_SCRAMBLE_KEY=$(openssl rand -hex 32)EOFThen start the container with that file. The values to replace are
placeholders: postgres.local and your-db-password are your database’s
host and password, and X.Y.Z is the release version.
docker run -d \ --name artist-alley \ -p 127.0.0.1:8080:8080 \ --env-file artist-alley.env \ -e AA_DB_HOST=postgres.local \ -e AA_DB_USER=artist_alley \ -e AA_DB_PASSWORD=your-db-password \ -e AA_DB_NAME=artist_alley \ -v artist-alley-storage:/var/lib/aa-storage \ ghcr.io/artist-alley-org/artist-alley:X.Y.ZThe 127.0.0.1 in the port mapping keeps the server reachable only from
this machine. The server speaks plain HTTP, so when other people need to
reach it, put it behind a reverse proxy that serves HTTPS rather than
publishing the port directly.
First sign-in
Section titled “First sign-in”On first boot the server creates an admin account with a random
password and prints it in its log, between two lines of = signs:
docker logs artist-alley 2>&1 | grep -A3 "FIRST-BOOT"Open http://localhost:8080, sign in as admin
with that password, and change it. There is no setup wizard to walk
through on a normal install. AA_BOOTSTRAP_DEFAULT_ADMIN=1 creates
admin with a published development password instead; never set it on a
real install.
Tag fan-out
Section titled “Tag fan-out”Release tags have no leading v: the v0.11.0 release is pulled as
:0.11.0, and its line as :0.11.
| Tag | Updated when |
|---|---|
:X.Y.Z | one release (recommended for pinning) |
:X.Y, :X | moves to the newest release on that line |
:latest | moves to each new stable (non-pre-release) release |
:edge | newest build from dev (continuous, not stable) |
:edge-<short-sha> | the build of one dev commit. Docs-only commits get no image. |
A tag is a name the registry can point somewhere else. To pin exactly
the bytes you tested, pull by digest (@sha256:...) instead.
Compose example
Section titled “Compose example”Put the two keys and a database password in a .env file next to
compose.yaml, generated once and kept:
# Run this once in the directory that holds compose.yaml, then keep .env safe.umask 077cat > .env <<EOFAA_MASTER_KEY=$(openssl rand -base64 32)AA_SCRAMBLE_KEY=$(openssl rand -hex 32)DB_PASSWORD=$(openssl rand -hex 16)EOFReplace X.Y.Z with the release version.
services: app: image: ghcr.io/artist-alley-org/artist-alley:X.Y.Z ports: ["127.0.0.1:8080:8080"] environment: AA_DB_HOST: postgres AA_DB_USER: artist_alley AA_DB_PASSWORD: ${DB_PASSWORD:?set in .env} AA_DB_NAME: artist_alley AA_SCRAMBLE_KEY: ${AA_SCRAMBLE_KEY:?set in .env} AA_MASTER_KEY: ${AA_MASTER_KEY:?set in .env} volumes: - storage:/var/lib/aa-storage depends_on: postgres: condition: service_healthy restart: unless-stopped
postgres: image: pgvector/pgvector:pg16 environment: POSTGRES_DB: artist_alley POSTGRES_USER: artist_alley POSTGRES_PASSWORD: ${DB_PASSWORD:?set in .env} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U artist_alley -d artist_alley"] interval: 5s timeout: 5s retries: 20 restart: unless-stopped
volumes: storage: pgdata:Then docker compose up -d. The app waits for Postgres to report
healthy before it starts, and its first-boot password is in
docker compose logs app (see First sign-in). The
pgdata and storage volumes and the .env file together are the
install; keep all three.
Building from source
Section titled “Building from source”git clone https://github.com/Artist-Alley-Org/artist-alleycd artist-alleydocker build -t artist-alley:local .This is the same multi-stage build the published images use: it builds
the SvelteKit frontend with npm, embeds it in the Go binary, and
packages the binary with the tools it calls at runtime (ffmpeg,
ImageMagick, Ghostscript, Chromium and others). On your machine you need
only Git and Docker with BuildKit, which the Dockerfile’s cache mounts
require. Run the result exactly like the published image, with
artist-alley:local as the image name.
There is no supported build of a standalone native binary yet: the binary depends on those runtime tools, which only the image provides. See Other channels.
Other channels (planned)
Section titled “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 planned,
tracked in issue #242.
Until then, run the Docker image (behind your existing reverse proxy
for TLS) or build from source.
Verifying signatures
Section titled “Verifying signatures”Docker images are keyless-signed via Sigstore.
Replace X.Y.Z with a release version, without the v (for example
0.11.0):
cosign verify ghcr.io/artist-alley-org/artist-alley:X.Y.Z \ --certificate-identity-regexp "https://github.com/Artist-Alley-Org/artist-alley/.*" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com"The release workflow signs the image under every tag it publishes,
including the Docker Hub name, so the same check works for
mscrnt/artist-alley:X.Y.Z. :edge images are not signed.
Configuration reference
Section titled “Configuration reference”Process settings come from environment variables: pass them to the
container via -e flags or a compose environment: block (an
env_file works too). Install-wide settings, such as the site name,
SMTP, auth providers, AI providers and appearance, are stored in the
database and changed in the admin UI, not through the environment.
The table below is built from docs/install/config/aa.env.example,
a template the binary does not read. It lists the variables the template
sets by default; optional ones, such as the S3 storage variables, are
documented in the template itself. Where the table and the binary
disagree, the binary’s behaviour is what counts.
The Default column shows the template’s example values, not the values the binary or the image falls back to, and its passwords and keys are placeholders that must be replaced. Where this matters for the commands on this page:
AA_DB_HOST: the template sayslocalhost; the binary’s own default ispostgres. Set it to your database’s host.AA_STORAGE_FS_ROOT: the template says/var/lib/artist-alley; the Docker image sets/var/lib/aa-storage, the path the examples mount.AA_DB_PASSWORD,AA_SCRAMBLE_KEY,AA_MASTER_KEY: the template values are placeholders. The server refuses the master-key placeholder at boot; generate both keys as described above.
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 | The Docker image sets this to /var/lib/aa-storage (the image’s VOLUME). A binary run without the variable uses /var/lib/artist-alley/storage. Set it to wherever your storage is mounted. |
Logging
| Variable | Default | Notes |
|---|---|---|
AA_LOG_LEVEL | info | |
AA_LOG_FORMAT | json |
Password-hashing pepper
| Variable | Default | Notes |
|---|---|---|
AA_SCRAMBLE_KEY | change-me-to-32-hex-bytes | Mixed into every password hash. Keep it stable across restarts. Generate with: openssl rand -hex 32 |
At-rest encryption master key
| Variable | Default | Notes |
|---|---|---|
AA_MASTER_KEY | required | Base64-encoded 32 bytes; generate it 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. |