For operators
Artist Alley aims to be simple to operate: one application container, one database, one storage location. There’s no message bus and no microservices in the core. The image carries the app together with the media tools it runs to build previews and thumbnails, including Node and a headless Chromium for 3D previews, so there’s no separate preview service to run. No add-on containers ship today. The optional AI integrations are experimental, stay off until an admin sets them up, and connect to model servers or provider APIs you run. Searching by image is further off: some of the code exists, but there’s no supported way to set it up yet, and it’s planned to arrive with installable add-ons.
The shape
Section titled “The shape”- One container image. The Go binary embeds the SvelteKit web app
via
go:embed, and the image packages it with the tools it calls at runtime. Updating the app means running a newer image. - Postgres-only. No MySQL and no Redis: records, full-text search and vectors share one Postgres database, and caching happens inside the app. See ADR 0006 and ADR 0013.
- Two layers of configuration. Process settings (database, keys, storage backend, logging) come from environment variables. Install-wide settings (site, SMTP, auth providers, AI providers, appearance) are stored in the database and changed in the admin UI.
- Backup is the database, your stored files, and both keys.
pg_dump, the storage volume or S3 bucket, and the originalAA_MASTER_KEYandAA_SCRAMBLE_KEY. Standard tools are enough; there’s no special export format.
Install + run
Section titled “Install + run”Releases ship as a Docker image (multi-arch, GHCR + Docker Hub). Native packages, binaries and a systemd path are planned (#242). Follow the Install guide, which has the full Docker and Compose steps.
The server won’t start without three settings: AA_DB_PASSWORD,
AA_SCRAMBLE_KEY (the password-hashing pepper) and AA_MASTER_KEY
(the at-rest encryption key). Generate the two keys once, as the
Install guide shows, store them somewhere safe, and pass the same
values every time you restart or replace the container. A new
AA_SCRAMBLE_KEY stops every existing password from working, and a
new or lost AA_MASTER_KEY means losing everything it encrypted.
The Install guide’s examples publish the port on 127.0.0.1, so the
server is reachable only from the same machine. The server speaks plain
HTTP; before other people use it, put it behind a reverse proxy that
serves HTTPS.
Release channels
Section titled “Release channels”Artist Alley is pre-1.0 and in active development. A release is a named version you can pin, not a statement that it is ready for production; pin an exact release so upgrades happen when you choose.
Release tags have no leading v: the v0.11.0 release is pulled as
:0.11.0, and its line as :0.11.
| Channel | Updated when | Use for |
|---|---|---|
:X.Y.Z | one release | pinning a release (recommended) |
:X.Y, :X | moves to the newest release on that line | following one release line |
:latest | moves to each new stable (non-pre-release) release | trying the newest release |
:edge | newest build from dev (continuous, not stable) | previewing unreleased work |
:edge-<short-sha> | the build of one dev commit, when one was built | pinning a specific dev build |
Every tag here is a name the registry can point somewhere else. To run
exactly the image you tested, pin it by digest (@sha256:...).
Edge images are built from pushes to dev that change the application.
Docs-only commits get no image, and a build that a newer push replaces
may never finish, so not every dev commit has an :edge-<short-sha>
tag.
Release images are multi-arch (amd64 + arm64) and are signed by the
release workflow via Sigstore; see the
Install guide § Verifying signatures.
The :edge images are amd64 only and are not signed.
Postgres
Section titled “Postgres”You need PostgreSQL 15 or newer with the pgvector extension (0.5.0 or
newer). Artist Alley creates its schema on first run via embedded
goose migrations, and applies any new ones each time it starts;
there’s no separate “migrate container” or “create database” step
beyond the initial role and database. Replace your-db-password with
a strong password, and give the app the same value as AA_DB_PASSWORD:
CREATE ROLE artist_alley WITH LOGIN SUPERUSER PASSWORD 'your-db-password';CREATE DATABASE artist_alley OWNER artist_alley;The role Artist Alley connects as must be a superuser. The first
migration creates the pgvector extension and sets a comment on it:
Postgres lets only a superuser create pgvector (it is not a trusted
extension), and only the extension’s owner comment on it, so creating
the extension in advance as a different superuser is not enough. The
official postgres and pgvector/pgvector images make POSTGRES_USER
a superuser, which is why the compose example in the
Install guide works as is.
The migrations enable four extensions: vector (pgvector, which is
installed separately; a
pgvector/pgvector image
is the simplest route) plus pg_trgm, pgcrypto and uuid-ossp,
which ship with standard Postgres. The schema also uses
UNIQUE NULLS NOT DISTINCT constraints, which is why PostgreSQL 15 is
the minimum.
Storage
Section titled “Storage”Two backends:
-
fs(default): files underAA_STORAGE_FS_ROOT, which the Docker image sets to/var/lib/aa-storageinside the container. Mount a named volume or a host directory there, as the Install guide’s examples do. Without a mount, Docker creates an anonymous volume, which is easy to lose track of when the container is replaced. Artist Alley manages this directory itself; don’t add, rename or edit files in it by hand. -
s3: any S3-compatible API (AWS S3, Cloudflare R2, Backblaze B2, MinIO). SetAA_STORAGE_BACKEND=s3andAA_STORAGE_S3_BUCKET, which is required. The rest depends on your provider:AA_STORAGE_S3_REGIONdefaults tous-east-1; set it to match your provider and bucket.AA_STORAGE_S3_ENDPOINTnormally stays unset for AWS S3. For other providers, set it to the provider’s S3 URL.AA_STORAGE_S3_ACCESS_KEYandAA_STORAGE_S3_SECRET_KEYare used only as a pair. Leave both unset to use the AWS SDK’s default credential chain instead, such as the standard AWS environment variables or an IAM role.AA_STORAGE_S3_USE_PATH_STYLEdefaults totrue, which suits MinIO. Set it tofalsefor AWS S3, Cloudflare R2 and Backblaze B2.
The Install guide § Configuration reference links the annotated template, which has more detail.
Storage is content-addressed: every stored file is keyed by its SHA-256, so the same bytes are stored only once across the whole install, and files are laid out by hash rather than in project folders. The database is what connects those files to posts, names and fields, so the storage is only useful together with the database. See ADR 0008 - Storage architecture.
Backup
Section titled “Backup”A restorable backup has four parts: the database, the stored files, and the two original keys.
Stop the app first (docker stop artist-alley, or
docker compose stop app), keep it stopped while you take both the
database dump and the copy of the stored files, and start it again once
you have both. A backup taken while the app runs needs the database and
the files snapshotted together, and a restore you have tested.
Database. From a machine that can reach your Postgres server,
replacing postgres.local with its host:
pg_dump -Fc -h postgres.local -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpWith the Install guide’s compose example, run it inside the postgres
service instead:
docker compose exec -T postgres pg_dump -Fc -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpStored files (originals and every generated preview) depend on your storage backend:
-
fsin a named volume (the Install guide’s examples): copy the volume’s contents with a short-lived container. This writes a compressed archive of theartist-alley-storagevolume to the current directory:Terminal window docker run --rm \-v artist-alley-storage:/data:ro \-v "$PWD":/backup \alpine tar -czf /backup/artist-alley-storage-$(date +%Y%m%d).tar.gz -C /data .Compose puts the project name in front of its volume names, so the compose example’s
storagevolume has a name likemyproject_storage;docker volume lsshows it. -
fsin a host directory: if you mounted a directory from the host, for example-v /data/artist-alley/storage:/var/lib/aa-storage, copy that host directory, for examplersync -a /data/artist-alley/storage/ backup-host:/backups/artist-alley/storage/./var/lib/aa-storageis the path inside the container, not on the host. -
s3: keep a recoverable copy of the bucket’s objects that does not depend on the bucket itself, for example a scheduled copy to a separate bucket, account or provider that you have tested restoring from. There may be no local directory to copy. Bucket versioning and replication are useful extra protection, but on their own they are not a backup: a deleted bucket, a compromised account, or a deletion that replication copies across can take them out too.
Keys: keep the original AA_MASTER_KEY and AA_SCRAMBLE_KEY (for
example the artist-alley.env or .env file from the Install guide)
somewhere secure and separate from the database dump. Without
AA_MASTER_KEY, data encrypted at rest (two-factor secrets and
federation keys, for example) can’t be read; without AA_SCRAMBLE_KEY,
no existing password works.
Restore is the inverse: restore the database (pg_restore reads the
-Fc dump) and the stored files, then start the app with the same two
keys. There’s no “backup mode” toggle. Try a restore on a spare machine
before you depend on it.
Updating
Section titled “Updating”Take a restorable backup first (see Backup). Migrations run automatically when the new version starts, and they only go forward: the server has no command to undo them, and starting an older image against an upgraded database doesn’t roll the schema back. To go back, restore the backup you took before upgrading.
For Docker, replace the container with one running the new release,
using the same key file, database settings and storage volume as
before. With the Install guide’s options, and X.Y.Z as the new
release version:
docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Zdocker stop artist-alleydocker rm artist-alleydocker 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.ZRemoving the container doesn’t touch the named volume or the database, so the stored files and records carry over. If you started it with different options, use yours.
For Compose, change the image: tag in compose.yaml to the new
release, then, in the same directory and with the same .env:
docker compose pull appdocker compose up -d appThe migration policy (ADR 0046) provides for one more fold of the migration history into a fresh baseline before the 1.0 release, and there is no supported upgrade path across a fold. From 1.0 on, migrations only append.
A systemd + native-package update path is planned with the native packaging work (#242).
Observability
Section titled “Observability”- Health:
GET /healthzandGET /readyzcurrently run the same check. The server pings the database (with a two-second timeout) and returns 200 with a short JSON status (includingstatus,version,uptimeanddatabase), or 503 with"status": "degraded"when the database doesn’t answer. For example,curl -fsS http://localhost:8080/healthz. - Structured logs:
AA_LOG_FORMAT=json(the default) for ingestable JSON, ortextfor humans.AA_LOG_LEVELcontrols verbosity (defaultinfo). - Metrics: a Prometheus-compatible scrape endpoint is planned; see ADR 0033. The server doesn’t serve one yet.
Public browsing
Section titled “Public browsing”Off by default. A fresh install doesn’t show its library to signed-out visitors, and an upgrade won’t switch that on: the setting is stored only when an admin changes it, and no stored setting means off. Turning it on is a deliberate choice, made with the Public access switch on the admin Site settings page.
It is enforced by the server, not by hiding pages. With it off, the server refuses signed-out requests to the browsing API (assets and their files, collections, the posts feed, featured items, search, public profiles and IIIF), rather than just leaving those pages out of navigation. What the install needs before anyone signs in, such as sign-in, first-boot setup and its appearance settings, works in both states. Other routes keep their own access checks.
With it on, the rule for signed-out visitors is public material only: published assets at the public tier, and collections and posts marked Public. Team, restricted and embargoed content is kept from them, downloads included. They get a front page with a curated featured rail, asset and collection browsing, search, public profile pages and a feed of public posts. For signed-in users, sensitivity is enforced on the file contents rather than the listing, so restricted material they can’t open shows as a locked item instead of vanishing.
Public browsing arrived in v0.5.0, off by default. Later releases filled out the public pages and closed gaps: v0.6.0 added public profile pages, v0.7.0 fixed routes that showed anonymous visitors unpublished work, and v0.10.1 made it possible to mark a post Public at all and opened the signed-out browse feed. The release notes have the detail. If you run a library that must stay private, keep public access off and keep the server behind HTTPS and your own network controls.
First boot and password sign-in work normally with it off. Generic SSO (LDAP and SAML) is in the code but only switches on with a license feature that can’t be obtained today, so it isn’t available yet.
Federation
Section titled “Federation”Artist Alley instances can pair with each other over the ArchivePub protocol. Pairing sets up the connection; what gets shared over it is decided separately. Today, paired instances exchange likes and comments using authenticated requests. Sharing assets and posts between instances is planned.
Install-wide settings (auth providers, AI providers, fonts and the rest
of system_config) never federate: they stay on the instance they
belong to. User profiles record which server each user came from
(origin_server_id).
You can run a single instance and ignore federation entirely.
Operator-relevant ADRs
Section titled “Operator-relevant ADRs”- Go as the target backend; no sidecars: the current decision for one Go server on Postgres. It superseded the historical Postgres-only, no MySQL, which had superseded Adjunct Postgres data model.
- Storage architecture
- Caching strategy
- Migration baseline + squash policy
- Observability & operator telemetry (metrics and tracing, planned)