Getting started
Artist Alley ships as a Docker image: one Go program that serves both the API and the web app, packaged with the media tools it uses to build previews. It is pre-1.0 and in active development, so features are still landing and it isn’t production-ready yet. There are three common starting points; pick the one that matches what you’re doing.
I want to try it
Section titled “I want to try it”To look around without installing anything, use the
shared live demo (sign in with demo /
demo). To run your own instance, the quickest way is the published
Docker image. Point it at a Postgres
(your own, or one in the same compose stack); it needs PostgreSQL 15 or
newer with the pgvector extension, and the role it connects as must be a
superuser. See the
Install guide.
The server also needs two keys. AA_MASTER_KEY encrypts the instance’s
federation and per-user keys, and the server won’t start without it.
AA_SCRAMBLE_KEY is the password-hashing pepper. Generate both once
and reuse them every time you restart or replace the container: a new
scramble key stops every existing password from working, and a lost
master key means losing everything it encrypted. You need Docker and
OpenSSL for the steps below.
# 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 a version from the
releases page, without the leading v. The database
user and name default to artist_alley; set AA_DB_USER and AA_DB_NAME
if yours differ.
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_PASSWORD=your-db-password \ -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 this trial reachable only from
this machine. Open http://localhost:8080 and sign in as
admin. On first boot the server creates that account with a random
password and prints it in its log (docker logs artist-alley); see
First sign-in. Change it once
you’re in.
Your uploads live in two places, the records in Postgres and the files in
the artist-alley-storage volume, and the keys in artist-alley.env are
needed to use them. Removing and recreating the container is fine. To keep
what you’ve uploaded, keep all three together; any one of them alone isn’t
enough to restore an install (Backup). The Docker
Compose setup (and building from source) lives in the
Install guide.
I want to install it for a team
Section titled “I want to install it for a team”Read the Install guide: run the published Docker image behind your existing reverse proxy for TLS. The server itself speaks plain HTTP, so anything other people reach over a network should go through HTTPS. Pin an exact release version rather than a moving tag, so an update happens when you choose it. Distribution is Docker-only today; native packages (.deb/.rpm, Homebrew) and standalone binaries are planned. 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
Section titled “I want to hack on the code”Local development uses Docker Compose, and CI starts the same
docker-compose.yml, with an override for its shared runner that drops
host ports and caps memory.
Prerequisites
Section titled “Prerequisites”- Docker with Docker Compose v2, Git, and
openssl(the bootstrap script uses it to generate secrets) - Enough free disk for Postgres and the files you upload
- Free TCP ports for the stack: by default 8088 (the app, through nginx), 5173 (the Vite dev server) and 5433 (Postgres)
Boot the stack
Section titled “Boot the stack”git clone https://github.com/Artist-Alley-Org/artist-alley.gitcd artist-alley./scripts/bootstrap.shscripts/bootstrap.sh creates .env from .env.example, generates
the Postgres password and the two required keys (AA_SCRAMBLE_KEY and
AA_MASTER_KEY), then builds and starts the stack and waits a short while for it to
start up. It doesn’t confirm that everything is healthy; the checks under
Verifying the stack below do that. If a .env already exists, it leaves it alone. Copying
.env.example by hand is not enough: the server rejects its placeholder
master key at boot, and the other placeholder values aren’t secrets.
The app is served through nginx at
http://localhost:8088 (NGINX_HTTP_PORT in
.env), and the Vite dev server with hot reload runs on :5173. The
development stack sets AA_BOOTSTRAP_DEFAULT_ADMIN=1, so it creates
admin with the published development password ArtistAlleyMogul;
never set that flag on a real install. 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
Section titled “Verifying the stack”# Postgres ready:docker compose exec -T postgres pg_isready -U artist_alley -d artist_alley
# Hit the Go health endpoint:curl -fsS http://localhost:8088/healthz
# Run the integration tests:./scripts/test.shCI runs the same ./scripts/test.sh against its Compose stack; see
.github/workflows/ci.yml.
What to read next
Section titled “What to read next”- API reference: the API contract, with request and response shapes for each operation.
- Architecture: how the server, the web app, Postgres and file storage fit together.
- Architecture Decisions: the reasoning behind the big calls.