Aller au contenu

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.

  • 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 les AA_MASTER_KEY et AA_SCRAMBLE_KEY d’origine. Les outils standards suffisent ; il n’y a pas de format d’export spécial.

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.

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.

CanalMis à jour quandÀ utiliser pour
:X.Y.Zune version préciseépingler une version (recommandé)
:X.Y, :Xpointe vers la version la plus récente de cette lignesuivre une ligne de versions
:latestpointe vers chaque nouvelle version stable (hors préversion)essayer la version la plus récente
:edgele 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.

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.

Deux backends :

  • fs (par défaut) : les fichiers sont placés sous AA_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éfinissez AA_STORAGE_BACKEND=s3 et AA_STORAGE_S3_BUCKET, qui est obligatoire. Le reste dépend de votre fournisseur :

    • AA_STORAGE_S3_REGION vaut us-east-1 par défaut ; faites-la correspondre à votre fournisseur et à votre bucket.
    • AA_STORAGE_S3_ENDPOINT reste normalement non défini pour AWS S3. Pour les autres fournisseurs, indiquez l’URL S3 du fournisseur.
    • AA_STORAGE_S3_ACCESS_KEY et AA_STORAGE_S3_SECRET_KEY ne 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_STYLE vaut true par défaut, ce qui convient à MinIO. Définissez-la à false pour 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.

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 :

Fenêtre de terminal
pg_dump -Fc -h postgres.local -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dump

Avec l’exemple Compose du guide d’installation, lancez-la plutôt dans le service postgres :

Fenêtre de terminal
docker compose exec -T postgres pg_dump -Fc -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dump

Fichiers stockés (originaux et tous les aperçus générés) : cela dépend de votre backend de stockage :

  • fs dans 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 volume artist-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 storage de l’exemple Compose porte donc un nom comme myproject_storage ; docker volume ls l’affiche.

  • fs dans 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 exemple rsync -a /data/artist-alley/storage/ backup-host:/backups/artist-alley/storage/. /var/lib/aa-storage est 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.

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 :

Fenêtre de terminal
docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z
docker stop artist-alley
docker rm artist-alley
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

Supprimer 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 :

Fenêtre de terminal
docker compose pull app
docker compose up -d app

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

  • Santé : GET /healthz et GET /readyz exé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 (dont status, version, uptime et database), 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, ou text pour les humains. AA_LOG_LEVEL contrôle la verbosité (info par défaut).
  • Métriques : un point de collecte compatible Prometheus est prévu ; voir l’ADR 0033. Le serveur n’en sert pas encore.

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.

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.