Skip to content

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.

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.

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

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_PASSWORD=your-db-password \
-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 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.

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.

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.

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

scripts/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.

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

CI runs the same ./scripts/test.sh against its Compose stack; see .github/workflows/ci.yml.