Aller au contenu

Installer Artist Alley

Artist Alley est distribué sous forme d’image Docker : un seul binaire Go avec le frontend SvelteKit intégré via go:embed, livré avec les outils d’exécution qu’il appelle. Apportez votre propre Postgres et un répertoire de stockage accessible en écriture ou un bucket compatible S3. Artist Alley est en version préliminaire (pré-1.0) et en plein développement : des fonctionnalités arrivent encore et il n’est pas prêt pour la production.

Les images de version sont multi-architecture (amd64 + arm64) et sont publiées à la fois sur GHCR et sur Docker Hub à partir du même build ; les images continues :edge sont uniquement amd64. Des paquets natifs et des binaires sont prévus ; voir Autres canaux.

Dans les commandes de téléchargement, X.Y.Z est la version que vous choisissez sur la page des versions, sans le v initial.

CanalIdéal pourTéléchargement / installation
Docker (GHCR)La plupart des utilisateurs, voie la plus rapidedocker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z
Docker HubLa même image, autre registredocker pull mscrnt/artist-alley:X.Y.Z
SourcesConstruire vous-même l’imagecloner le dépôt, docker build (voir Compiler depuis les sources)

Les images de version sont signées via Sigstore, contrairement aux images :edge (cosign verify, voir Vérifier les signatures).

  • Docker pour exécuter l’image, et OpenSSL pour générer les clés ci-dessous.
  • PostgreSQL 15 ou plus récent, avec l’extension pgvector (0.5.0 ou plus récente). Apportez le vôtre ; Artist Alley crée son propre schéma au premier lancement via des migrations intégrées. Ces migrations activent aussi pg_trgm, pgcrypto et uuid-ossp, fournis avec Postgres standard, mais pgvector s’installe séparément. Le plus simple est d’utiliser une image pgvector/pgvector à la place de postgres seul, comme dans l’exemple Compose ci-dessous. Le rôle de base de données avec lequel Artist Alley se connecte doit être un superutilisateur ; voir Pour les opérateurs.
  • Un répertoire de stockage (blobs binaires + miniatures générées) ou un bucket compatible S3 (MinIO, Backblaze B2, Cloudflare R2, AWS S3 ; tous pris en charge via AA_STORAGE_BACKEND=s3).
  • Un poivre de hachage des mots de passe (AA_SCRAMBLE_KEY) : openssl rand -hex 32. Gardez-le stable d’un redémarrage ou d’un remplacement de conteneur à l’autre ; un nouveau poivre empêche tous les mots de passe existants de fonctionner.
  • Une clé de chiffrement au repos (AA_MASTER_KEY) : openssl rand -base64 32. Obligatoire au démarrage ; elle chiffre les clés de fédération et les clés par utilisateur, et la perdre revient à perdre tout ce qu’elle a chiffré.

Générez les deux clés une seule fois, rangez-les en lieu sûr et réutilisez-les à chaque redémarrage ou remplacement du conteneur. Une installation restaurable, c’est la base de données, les fichiers stockés et les deux clés réunis (Sauvegarde).


Écrivez les deux clés dans un fichier, une seule fois :

Fenêtre de terminal
# 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

Démarrez ensuite le conteneur avec ce fichier. Les valeurs à remplacer sont des substituts : postgres.local et your-db-password sont l’hôte et le mot de passe de votre base de données, et X.Y.Z est la version.

Fenêtre de terminal
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

Le 127.0.0.1 dans la redirection de port limite l’accès au serveur à cette seule machine. Le serveur parle en HTTP simple ; lorsque d’autres personnes doivent y accéder, placez-le derrière un reverse proxy qui sert du HTTPS plutôt que de publier directement le port.

Au premier démarrage, le serveur crée un compte admin avec un mot de passe aléatoire et l’affiche dans son journal, entre deux lignes de signes = :

Fenêtre de terminal
docker logs artist-alley 2>&1 | grep -A3 "FIRST-BOOT"

Ouvrez http://localhost:8080, connectez-vous avec admin et ce mot de passe, puis changez-le. Il n’y a pas d’assistant de configuration à parcourir pour une installation normale. AA_BOOTSTRAP_DEFAULT_ADMIN=1 crée à la place admin avec un mot de passe de développement public ; ne le définissez jamais sur une installation réelle.

Les tags de version n’ont pas de v initial : la version v0.11.0 se télécharge sous :0.11.0, et sa ligne sous :0.11.

TagMis à jour quand
:X.Y.Zune version précise (recommandé pour épingler)
:X.Y, :Xpointe vers la version la plus récente de cette ligne
:latestpointe vers chaque nouvelle version stable (hors préversion)
:edgele build le plus récent de dev (continu, non stable)
:edge-<short-sha>le build d’un commit de dev. Les commits ne touchant que la documentation n’ont pas d’image.

Un tag est un nom que le registre peut faire pointer ailleurs. Pour épingler exactement les octets que vous avez testés, téléchargez plutôt par digest (@sha256:...).

Placez les deux clés et un mot de passe de base de données dans un fichier .env à côté de compose.yaml, généré une seule fois puis conservé :

Fenêtre de terminal
# 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

Remplacez X.Y.Z par la 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:

Lancez ensuite docker compose up -d. L’application attend que Postgres soit déclaré sain avant de démarrer, et son mot de passe de premier démarrage se trouve dans docker compose logs app (voir Première connexion). Les volumes pgdata et storage et le fichier .env forment ensemble l’installation ; gardez les trois.

Fenêtre de terminal
git clone https://github.com/Artist-Alley-Org/artist-alley
cd artist-alley
docker build -t artist-alley:local .

C’est le même build multi-étapes que celui des images publiées : il construit le frontend SvelteKit avec npm, l’intègre dans le binaire Go, puis empaquette le binaire avec les outils qu’il appelle à l’exécution (ffmpeg, ImageMagick, Ghostscript, Chromium et d’autres). Sur votre machine, il vous suffit de Git et de Docker avec BuildKit, dont les montages de cache du Dockerfile ont besoin. Lancez le résultat exactement comme l’image publiée, avec artist-alley:local comme nom d’image.

Il n’existe pas encore de build pris en charge d’un binaire natif autonome : le binaire dépend de ces outils d’exécution, que seule l’image fournit. Voir Autres canaux.


Les versions sont aujourd’hui uniquement distribuées par Docker. La distribution native (paquets .deb / .rpm avec une unité systemd renforcée, binaires statiques pour Linux/macOS/Windows et un tap Homebrew) est prévue, suivie dans l’issue #242. D’ici là, utilisez l’image Docker (derrière votre reverse proxy existant pour le TLS) ou compilez depuis les sources.


Les images Docker sont signées sans clé (keyless) via Sigstore. Remplacez X.Y.Z par une version, sans le v (par exemple 0.11.0) :

Fenêtre de terminal
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"

Le workflow de publication signe l’image sous chaque tag qu’il publie, y compris le nom Docker Hub ; la même vérification fonctionne donc pour mscrnt/artist-alley:X.Y.Z. Les images :edge ne sont pas signées.


Les paramètres du processus viennent de variables d’environnement : transmettez-les au conteneur avec des options -e ou un bloc environment: de Compose (un env_file fonctionne aussi). Les paramètres valables pour toute l’installation, comme le nom du site, le SMTP, les fournisseurs d’authentification, les fournisseurs d’IA et l’apparence, sont stockés dans la base de données et modifiés dans l’interface d’administration, pas via l’environnement.

Le tableau ci-dessous est construit à partir de docs/install/config/aa.env.example, un modèle que le binaire ne lit pas. Il liste les variables que le modèle définit par défaut ; les variables facultatives, comme celles du stockage S3, sont documentées dans le modèle lui-même. En cas de désaccord entre le tableau et le binaire, c’est le comportement du binaire qui fait foi.

La colonne Default (valeur par défaut) montre les valeurs d’exemple du modèle, pas les valeurs de repli du binaire ou de l’image, et ses mots de passe et clés sont des substituts à remplacer. Voici les points qui comptent pour les commandes de cette page :

  • AA_DB_HOST : le modèle indique localhost ; la valeur par défaut du binaire est postgres. Définissez l’hôte de votre base de données.
  • AA_STORAGE_FS_ROOT : le modèle indique /var/lib/artist-alley ; l’image Docker définit /var/lib/aa-storage, le chemin que montent les exemples.
  • AA_DB_PASSWORD, AA_SCRAMBLE_KEY, AA_MASTER_KEY : les valeurs du modèle sont des substituts. Le serveur refuse au démarrage la clé maître factice ; générez les deux clés comme décrit plus haut.

Le tableau généré ci-dessous est une référence technique et reste en anglais, y compris ses en-têtes de colonnes et ses descriptions.

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.