Pour les opérateurs
Artist Alley vise à rester simple à exploiter : un conteneur d’application, une base de données, un emplacement de stockage. Il n’y a ni bus de messages ni microservices dans le cœur. L’image embarque l’application ainsi que les outils multimédias qu’elle exécute pour générer les aperçus et les miniatures, dont Node et un Chromium sans interface pour les aperçus 3D ; il n’y a donc pas de service d’aperçu distinct à faire tourner. Aucun conteneur de module complémentaire n’est livré aujourd’hui. Les intégrations d’IA facultatives sont expérimentales, restent désactivées tant qu’un administrateur ne les a pas configurées, et se connectent à des serveurs de modèles ou à des API de fournisseurs que vous exploitez. La recherche par image est plus lointaine : une partie du code existe, mais il n’y a pas encore de moyen pris en charge de la mettre en place, et elle devrait arriver avec les modules complémentaires installables.
Vue d’ensemble
Section intitulée « Vue d’ensemble »- Une seule image de conteneur. Le binaire Go embarque l’application web
SvelteKit via
go:embed, et l’image le livre avec les outils qu’il appelle à l’exécution. Mettre l’application à jour, c’est lancer une image plus récente. - Postgres uniquement. Ni MySQL ni Redis : les enregistrements, la recherche en texte intégral et les vecteurs partagent une seule base Postgres, et la mise en cache se fait à l’intérieur de l’application. Voir l’ADR 0006 et l’ADR 0013.
- Deux niveaux de configuration. Les paramètres du processus (base de données, clés, backend de stockage, journalisation) viennent de variables d’environnement. Les paramètres valables pour toute l’installation (site, SMTP, fournisseurs d’authentification, fournisseurs d’IA, apparence) sont stockés dans la base de données et modifiés dans l’interface d’administration.
- La sauvegarde, c’est la base de données, vos fichiers stockés et les
deux clés.
pg_dump, le volume de stockage ou le bucket S3, ainsi que lesAA_MASTER_KEYetAA_SCRAMBLE_KEYd’origine. Les outils standards suffisent ; il n’y a pas de format d’export spécial.
Installer et lancer
Section intitulée « Installer et lancer »Les versions sont livrées sous forme d’image Docker (multi-architecture, GHCR + Docker Hub). Des paquets natifs, des binaires et une voie systemd sont prévus (#242). Suivez le guide d’installation, qui détaille toutes les étapes Docker et Compose.
Le serveur ne démarre pas sans trois paramètres : AA_DB_PASSWORD,
AA_SCRAMBLE_KEY (le poivre de hachage des mots de passe) et
AA_MASTER_KEY (la clé de chiffrement au repos). Générez les deux clés
une seule fois, comme le montre le guide d’installation, rangez-les en
lieu sûr et transmettez les mêmes valeurs à chaque redémarrage ou
remplacement du conteneur. Une nouvelle AA_SCRAMBLE_KEY empêche tous les
mots de passe existants de fonctionner, et une AA_MASTER_KEY nouvelle ou
perdue revient à perdre tout ce qu’elle a chiffré.
Les exemples du guide d’installation publient le port sur 127.0.0.1 ; le
serveur n’est donc accessible que depuis la même machine. Le serveur parle
en HTTP simple ; avant que d’autres personnes l’utilisent, placez-le derrière
un reverse proxy qui sert du HTTPS.
Canaux de publication
Section intitulée « Canaux de publication »Artist Alley est en version préliminaire (pré-1.0) et en plein développement. Une version est un numéro nommé que vous pouvez épingler, pas une déclaration qu’elle est prête pour la production ; épinglez une version précise afin que les mises à niveau n’aient lieu que lorsque vous les décidez.
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.
| Canal | Mis à jour quand | À utiliser pour |
|---|---|---|
:X.Y.Z | une version précise | épingler une version (recommandé) |
:X.Y, :X | pointe vers la version la plus récente de cette ligne | suivre une ligne de versions |
:latest | pointe vers chaque nouvelle version stable (hors préversion) | essayer la version la plus récente |
:edge | le build le plus récent de dev (continu, non stable) | prévisualiser le travail non publié |
:edge-<short-sha> | le build d’un commit de dev, lorsqu’il y en a eu un | épingler un build de dev précis |
Chaque tag ci-dessus est un nom que le registre peut faire pointer ailleurs.
Pour exécuter exactement l’image que vous avez testée, épinglez-la par
digest (@sha256:...).
Les images edge sont construites à partir des pushes sur dev qui modifient
l’application. Les commits ne touchant que la documentation n’ont pas
d’image, et un build remplacé par un push plus récent peut ne jamais se
terminer ; tous les commits de dev n’ont donc pas de tag
:edge-<short-sha>.
Les images de version sont multi-architecture (amd64 + arm64) et sont
signées par le workflow de publication via Sigstore ; voir
Guide d’installation § Vérifier les signatures.
Les images :edge sont uniquement amd64 et ne sont pas signées.
Postgres
Section intitulée « Postgres »Il vous faut PostgreSQL 15 ou plus récent avec l’extension pgvector (0.5.0
ou plus récente). Artist Alley crée son schéma au premier lancement via des
migrations goose intégrées, et applique les nouvelles à chaque démarrage ;
il n’y a pas de « conteneur de migration » ni d’étape « créer la base » à
part, en dehors du rôle et de la base initiaux. Remplacez
your-db-password par un mot de passe robuste, et donnez à l’application la
même valeur dans AA_DB_PASSWORD :
CREATE ROLE artist_alley WITH LOGIN SUPERUSER PASSWORD 'your-db-password';CREATE DATABASE artist_alley OWNER artist_alley;Le rôle avec lequel Artist Alley se connecte doit être un superutilisateur.
La première migration crée l’extension pgvector et y ajoute un commentaire :
Postgres ne laisse un superutilisateur créer pgvector que parce qu’elle
n’est pas une extension de confiance (trusted), et seul le propriétaire de
l’extension peut la commenter ; créer l’extension à l’avance avec un autre
superutilisateur ne suffit donc pas. Les images officielles postgres et
pgvector/pgvector font de POSTGRES_USER un superutilisateur, ce qui
explique que l’exemple Compose du
guide d’installation
fonctionne tel quel.
Les migrations activent quatre extensions : vector (pgvector, qui
s’installe séparément ; une image
pgvector/pgvector est le
plus simple) ainsi que pg_trgm, pgcrypto et uuid-ossp, fournis avec
Postgres standard. Le schéma utilise aussi des contraintes
UNIQUE NULLS NOT DISTINCT, ce qui explique que PostgreSQL 15 soit le
minimum.
Stockage
Section intitulée « Stockage »Deux backends :
-
fs(par défaut) : les fichiers sont placés sousAA_STORAGE_FS_ROOT, que l’image Docker définit à/var/lib/aa-storageà l’intérieur du conteneur. Montez-y un volume nommé ou un répertoire de l’hôte, comme le font les exemples du guide d’installation. Sans montage, Docker crée un volume anonyme, facile à perdre de vue quand le conteneur est remplacé. Artist Alley gère ce répertoire lui-même ; n’y ajoutez, renommez ou modifiez aucun fichier à la main. -
s3: toute API compatible S3 (AWS S3, Cloudflare R2, Backblaze B2, MinIO). DéfinissezAA_STORAGE_BACKEND=s3etAA_STORAGE_S3_BUCKET, qui est obligatoire. Le reste dépend de votre fournisseur :AA_STORAGE_S3_REGIONvautus-east-1par défaut ; faites-la correspondre à votre fournisseur et à votre bucket.AA_STORAGE_S3_ENDPOINTreste normalement non défini pour AWS S3. Pour les autres fournisseurs, indiquez l’URL S3 du fournisseur.AA_STORAGE_S3_ACCESS_KEYetAA_STORAGE_S3_SECRET_KEYne s’utilisent qu’en paire. Laissez les deux non définies pour utiliser à la place la chaîne d’identifiants par défaut du SDK AWS, comme les variables d’environnement AWS standard ou un rôle IAM.AA_STORAGE_S3_USE_PATH_STYLEvauttruepar défaut, ce qui convient à MinIO. Définissez-la àfalsepour AWS S3, Cloudflare R2 et Backblaze B2.
Le guide d’installation § Référence de configuration renvoie vers le modèle annoté, qui donne plus de détails.
Le stockage est adressé par contenu : chaque fichier stocké est identifié par son SHA-256, de sorte que les mêmes octets ne sont stockés qu’une seule fois pour toute l’installation, et les fichiers sont organisés par empreinte plutôt que dans des dossiers de projet. C’est la base de données qui relie ces fichiers aux publications, aux noms et aux champs ; le stockage n’est donc utile qu’avec la base de données. Voir l’ADR 0008 - Storage architecture.
Sauvegarde
Section intitulée « Sauvegarde »Une sauvegarde restaurable comporte quatre éléments : la base de données, les fichiers stockés et les deux clés d’origine.
Arrêtez d’abord l’application (docker stop artist-alley, ou
docker compose stop app), gardez-la arrêtée pendant que vous réalisez à la
fois l’export de la base et la copie des fichiers stockés, puis redémarrez-la
quand vous avez les deux. Une sauvegarde faite pendant que l’application
tourne exige que la base et les fichiers soient capturés ensemble, et une
restauration que vous avez testée.
Base de données. Depuis une machine qui peut joindre votre serveur
Postgres, en remplaçant postgres.local par son hôte :
pg_dump -Fc -h postgres.local -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpAvec l’exemple Compose du guide d’installation, lancez-la plutôt dans le
service postgres :
docker compose exec -T postgres pg_dump -Fc -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpFichiers stockés (originaux et tous les aperçus générés) : cela dépend de votre backend de stockage :
-
fsdans un volume nommé (les exemples du guide d’installation) : copiez le contenu du volume avec un conteneur éphémère. Cela écrit dans le répertoire courant une archive compressée du volumeartist-alley-storage:Fenêtre de terminal 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 fait précéder les noms de ses volumes du nom du projet ; le volume
storagede l’exemple Compose porte donc un nom commemyproject_storage;docker volume lsl’affiche. -
fsdans un répertoire de l’hôte : si vous avez monté un répertoire de l’hôte, par exemple-v /data/artist-alley/storage:/var/lib/aa-storage, copiez ce répertoire de l’hôte, par exemplersync -a /data/artist-alley/storage/ backup-host:/backups/artist-alley/storage/./var/lib/aa-storageest le chemin à l’intérieur du conteneur, pas sur l’hôte. -
s3: conservez une copie récupérable des objets du bucket qui ne dépend pas du bucket lui-même, par exemple une copie planifiée vers un autre bucket, compte ou fournisseur dont vous avez testé la restauration. Il peut n’y avoir aucun répertoire local à copier. Le versionnement et la réplication du bucket sont une protection supplémentaire utile, mais ils ne constituent pas une sauvegarde à eux seuls : un bucket supprimé, un compte compromis, ou une suppression que la réplication propage peuvent aussi les emporter.
Clés : conservez les AA_MASTER_KEY et AA_SCRAMBLE_KEY d’origine (par
exemple le fichier artist-alley.env ou .env du guide d’installation)
dans un endroit sûr et séparé de l’export de la base de données. Sans
AA_MASTER_KEY, les données chiffrées au repos (secrets d’authentification
à deux facteurs et clés de fédération, par exemple) ne peuvent pas être lues ;
sans AA_SCRAMBLE_KEY, aucun mot de passe existant ne fonctionne.
La restauration est l’opération inverse : restaurez la base de données
(pg_restore lit l’export -Fc) et les fichiers stockés, puis démarrez
l’application avec les deux mêmes clés. Il n’y a pas de bascule « mode
sauvegarde ». Essayez une restauration sur une machine de rechange avant de
vous y fier.
Mises à jour
Section intitulée « Mises à jour »Faites d’abord une sauvegarde restaurable (voir Sauvegarde). Les migrations s’exécutent automatiquement au démarrage de la nouvelle version, et elles ne vont que vers l’avant : le serveur n’a pas de commande pour les annuler, et démarrer une image plus ancienne sur une base mise à niveau ne ramène pas le schéma en arrière. Pour revenir en arrière, restaurez la sauvegarde faite avant la mise à niveau.
Avec Docker, remplacez le conteneur par un autre exécutant la nouvelle
version, avec le même fichier de clés, les mêmes paramètres de base de
données et le même volume de stockage qu’avant. Avec les options du guide
d’installation, et X.Y.Z comme nouvelle 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.ZSupprimer le conteneur ne touche ni au volume nommé ni à la base de données ; les fichiers stockés et les enregistrements sont donc conservés. Si vous l’avez démarré avec d’autres options, utilisez les vôtres.
Avec Compose, changez le tag de image: dans compose.yaml pour la
nouvelle version, puis, dans le même répertoire et avec le même .env :
docker compose pull appdocker compose up -d appLa politique de migration (ADR 0046) prévoit un dernier regroupement de l’historique des migrations en une nouvelle base de référence avant la version 1.0, et il n’existe aucun chemin de mise à niveau pris en charge au travers d’un regroupement. À partir de la 1.0, les migrations ne font que s’ajouter.
Une voie de mise à jour systemd + paquet natif est prévue avec le travail sur le paquetage natif (#242).
Observabilité
Section intitulée « Observabilité »- Santé :
GET /healthzetGET /readyzexécutent actuellement la même vérification. Le serveur interroge la base de données (avec un délai d’attente de deux secondes) et renvoie 200 avec un court état JSON (dontstatus,version,uptimeetdatabase), ou 503 avec"status": "degraded"lorsque la base de données ne répond pas. Par exemple,curl -fsS http://localhost:8080/healthz. - Journaux structurés :
AA_LOG_FORMAT=json(par défaut) pour du JSON exploitable par des outils d’ingestion, outextpour les humains.AA_LOG_LEVELcontrôle la verbosité (infopar défaut). - Métriques : un point de collecte compatible Prometheus est prévu ; voir l’ADR 0033. Le serveur n’en sert pas encore.
Navigation publique
Section intitulée « Navigation publique »Désactivée par défaut. Une nouvelle installation n’expose pas sa bibliothèque aux visiteurs non connectés, et une mise à niveau ne l’active pas : le paramètre n’est enregistré que lorsqu’un administrateur le modifie, et l’absence de paramètre enregistré signifie désactivé. L’activer est un choix délibéré, fait avec l’interrupteur Accès public de la page Paramètres du site de l’administration.
Elle est appliquée par le serveur, pas en masquant des pages. Lorsqu’elle est désactivée, le serveur refuse les requêtes non connectées vers l’API de navigation (ressources et leurs fichiers, collections, fil des publications, éléments à la une, recherche, profils publics et IIIF), au lieu de simplement omettre ces pages de la navigation. Ce dont l’installation a besoin avant que quiconque se connecte, comme la connexion, la configuration du premier démarrage et ses paramètres d’apparence, fonctionne dans les deux états. Les autres routes conservent leurs propres contrôles d’accès.
Lorsqu’elle est activée, la règle pour les visiteurs non connectés est de ne montrer que le contenu public : les ressources publiées au niveau public, et les collections et publications marquées Publiques. Le contenu d’équipe, restreint et sous embargo leur reste inaccessible, téléchargements compris. Ils disposent d’une page d’accueil avec une rubrique d’éléments à la une choisis, de la navigation dans les ressources et les collections, de la recherche, de pages de profil publiques et d’un fil de publications publiques. Pour les utilisateurs connectés, la sensibilité est appliquée au contenu des fichiers plutôt qu’à la liste : le contenu restreint qu’ils ne peuvent pas ouvrir apparaît comme un élément verrouillé au lieu de disparaître.
La navigation publique est arrivée dans la v0.5.0, désactivée par défaut. Les versions suivantes ont étoffé les pages publiques et comblé des lacunes : la v0.6.0 a ajouté les pages de profil publiques, la v0.7.0 a corrigé des routes qui montraient des travaux non publiés aux visiteurs anonymes, et la v0.10.1 a rendu possible le marquage d’une publication comme Publique, et ouvert le fil de navigation aux visiteurs non connectés. Les notes de version donnent le détail. Si vous exploitez une bibliothèque qui doit rester privée, laissez l’accès public désactivé et gardez le serveur derrière HTTPS et vos propres contrôles réseau.
Le premier démarrage et la connexion par mot de passe fonctionnent normalement quand elle est désactivée. Le SSO générique (LDAP et SAML) est dans le code, mais ne s’active qu’avec une fonctionnalité de licence impossible à obtenir aujourd’hui ; il n’est donc pas encore disponible.
Fédération
Section intitulée « Fédération »Les instances d’Artist Alley peuvent s’appairer entre elles via le protocole ArchivePub. L’appairage établit la connexion ; ce qui est partagé par ce biais se décide séparément. Aujourd’hui, les instances appairées échangent des mentions J’aime et des commentaires au moyen de requêtes authentifiées. Le partage de ressources et de publications entre instances est prévu.
Les paramètres valables pour toute l’installation (fournisseurs
d’authentification, fournisseurs d’IA, polices et le reste de
system_config) ne sont jamais fédérés : ils restent sur l’instance à
laquelle ils appartiennent. Les profils d’utilisateurs enregistrent le
serveur d’origine de chaque utilisateur (origin_server_id).
Vous pouvez exploiter une seule instance et ignorer complètement la fédération.
ADR utiles aux opérateurs
Section intitulée « ADR utiles aux opérateurs »- Go comme backend cible ; pas de sidecars : la décision actuelle d’un seul serveur Go sur Postgres. Elle a remplacé l’ADR historique Postgres uniquement, pas de MySQL, qui avait lui-même remplacé Adjunct Postgres data model.
- Architecture du stockage
- Stratégie de cache
- Base de migration + politique de regroupement
- Observabilité et télémétrie opérateur (métriques et traçage, prévus)