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.
Choix rapide
Section intitulée « Choix rapide »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.
| Canal | Idéal pour | Téléchargement / installation |
|---|---|---|
| Docker (GHCR) | La plupart des utilisateurs, voie la plus rapide | docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z |
| Docker Hub | La même image, autre registre | docker pull mscrnt/artist-alley:X.Y.Z |
| Sources | Construire vous-même l’image | cloner 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).
Prérequis
Section intitulée « Prérequis »- 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,pgcryptoetuuid-ossp, fournis avec Postgres standard, mais pgvector s’installe séparément. Le plus simple est d’utiliser une imagepgvector/pgvectorà la place depostgresseul, 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).
Docker (recommandé)
Section intitulée « Docker (recommandé) »Écrivez les deux clés dans un fichier, une seule fois :
# 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)EOFDé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.
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.ZLe 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.
Première connexion
Section intitulée « Première connexion »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
= :
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.
Déclinaison des tags
Section intitulée « Déclinaison des tags »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.
| Tag | Mis à jour quand |
|---|---|
:X.Y.Z | une version précise (recommandé pour épingler) |
:X.Y, :X | pointe vers la version la plus récente de cette ligne |
:latest | pointe vers chaque nouvelle version stable (hors préversion) |
:edge | le 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:...).
Exemple Compose
Section intitulée « Exemple Compose »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é :
# Run this once in the directory that holds compose.yaml, then keep .env safe.umask 077cat > .env <<EOFAA_MASTER_KEY=$(openssl rand -base64 32)AA_SCRAMBLE_KEY=$(openssl rand -hex 32)DB_PASSWORD=$(openssl rand -hex 16)EOFRemplacez X.Y.Z par la version.
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.
Compiler depuis les sources
Section intitulée « Compiler depuis les sources »git clone https://github.com/Artist-Alley-Org/artist-alleycd artist-alleydocker 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.
Autres canaux (prévus)
Section intitulée « Autres canaux (prévus) »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.
Vérifier les signatures
Section intitulée « Vérifier les signatures »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) :
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.
Référence de configuration
Section intitulée « Référence de configuration »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 indiquelocalhost; la valeur par défaut du binaire estpostgres. 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
| Variable | Default | Notes |
|---|---|---|
AA_HTTP_ADDR | :8080 |
Postgres
| Variable | Default | Notes |
|---|---|---|
AA_DB_HOST | localhost | |
AA_DB_PORT | 5432 | |
AA_DB_NAME | artist_alley | |
AA_DB_USER | artist_alley | |
AA_DB_PASSWORD | change-me | |
AA_DB_SSLMODE | disable |
Storage backend
| Variable | Default | Notes |
|---|---|---|
AA_STORAGE_BACKEND | fs | fs (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-alley | The 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
| Variable | Default | Notes |
|---|---|---|
AA_LOG_LEVEL | info | |
AA_LOG_FORMAT | json |
Password-hashing pepper
| Variable | Default | Notes |
|---|---|---|
AA_SCRAMBLE_KEY | change-me-to-32-hex-bytes | Mixed into every password hash. Keep it stable across restarts. Generate with: openssl rand -hex 32 |
At-rest encryption master key
| Variable | Default | Notes |
|---|---|---|
AA_MASTER_KEY | required | Base64-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. |