Skip to content

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.

In the pull commands, X.Y.Z is the release version you choose from the releases page, without the leading v.

ChannelBest forPull / install
Docker (GHCR)Most users, fastest pathdocker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z
Docker HubSame image, alternate registrydocker pull mscrnt/artist-alley:X.Y.Z
SourceBuilding the image yourselfclone the repo, docker build (see Building from source)

Release images are signed via Sigstore, and :edge images are not (cosign verify, see Verifying signatures).

  • 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, pgcrypto and uuid-ossp, which ship with standard Postgres, but pgvector is installed separately. The simplest route is a pgvector/pgvector image in place of plain postgres, 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).


Write the two keys to a file once:

Terminal window
# Run this once, then keep artist-alley.env somewhere safe.
umask 077
cat > artist-alley.env <<EOF
AA_MASTER_KEY=$(openssl rand -base64 32)
AA_SCRAMBLE_KEY=$(openssl rand -hex 32)
EOF

Then 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.

Terminal window
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.Z

The 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.

On first boot the server creates an admin account with a random password and prints it in its log, between two lines of = signs:

Terminal window
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.

Release tags have no leading v: the v0.11.0 release is pulled as :0.11.0, and its line as :0.11.

TagUpdated when
:X.Y.Zone release (recommended for pinning)
:X.Y, :Xmoves to the newest release on that line
:latestmoves to each new stable (non-pre-release) release
:edgenewest 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.

Put the two keys and a database password in a .env file next to compose.yaml, generated once and kept:

Terminal window
# Run this once in the directory that holds compose.yaml, then keep .env safe.
umask 077
cat > .env <<EOF
AA_MASTER_KEY=$(openssl rand -base64 32)
AA_SCRAMBLE_KEY=$(openssl rand -hex 32)
DB_PASSWORD=$(openssl rand -hex 16)
EOF

Replace X.Y.Z with the release version.

compose.yaml
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.

Terminal window
git clone https://github.com/Artist-Alley-Org/artist-alley
cd artist-alley
docker 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.


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.


Docker images are keyless-signed via Sigstore. Replace X.Y.Z with a release version, without the v (for example 0.11.0):

Terminal window
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.


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 says localhost; the binary’s own default is postgres. 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

VariableDefaultNotes
AA_HTTP_ADDR:8080

Postgres

VariableDefaultNotes
AA_DB_HOSTlocalhost
AA_DB_PORT5432
AA_DB_NAMEartist_alley
AA_DB_USERartist_alley
AA_DB_PASSWORDchange-me
AA_DB_SSLMODEdisable

Storage backend

VariableDefaultNotes
AA_STORAGE_BACKENDfsfs (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-alleyThe 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

VariableDefaultNotes
AA_LOG_LEVELinfo
AA_LOG_FORMATjson

Password-hashing pepper

VariableDefaultNotes
AA_SCRAMBLE_KEYchange-me-to-32-hex-bytesMixed into every password hash. Keep it stable across restarts. Generate with: openssl rand -hex 32

At-rest encryption master key

VariableDefaultNotes
AA_MASTER_KEYrequiredBase64-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.