Premiers pas
Artist Alley est distribué sous forme d’image Docker : un seul programme Go qui sert à la fois l’API et l’application web, livré avec les outils multimédias qu’il utilise pour générer les aperçus. Le projet 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. Il y a trois points de départ courants ; choisissez celui qui correspond à ce que vous voulez faire.
Je veux l’essayer
Section intitulée « Je veux l’essayer »Pour explorer sans rien installer, utilisez la
démo en ligne partagée (connectez-vous
avec demo / demo). Pour faire tourner votre propre instance, le plus
simple est l’image Docker publiée. Pointez-la vers un Postgres
(le vôtre, ou un Postgres du même stack Compose) ; il faut PostgreSQL 15
ou plus récent avec l’extension pgvector, et le rôle utilisé pour la
connexion doit être un superutilisateur. Consultez le
guide d’installation.
Le serveur a aussi besoin de deux clés. AA_MASTER_KEY chiffre les clés de
fédération et les clés par utilisateur de l’instance, et le serveur ne
démarre pas sans elle. AA_SCRAMBLE_KEY est le poivre (pepper) du hachage
des mots de passe. Générez les deux une seule fois et réutilisez-les à
chaque redémarrage ou remplacement du conteneur : une nouvelle clé
AA_SCRAMBLE_KEY empêche tous les mots de passe existants de fonctionner,
et perdre la clé maître revient à perdre tout ce qu’elle a chiffré. Pour
les étapes ci-dessous, il vous faut Docker et OpenSSL.
# 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 une version de la
page des versions, sans le v initial. L’utilisateur
et le nom de la base valent artist_alley par défaut ; définissez
AA_DB_USER et AA_DB_NAME si les vôtres sont différents.
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_PASSWORD=your-db-password \ -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 à cet essai à
cette seule machine. Ouvrez http://localhost:8080
et connectez-vous avec admin. Au premier démarrage, le serveur crée ce
compte avec un mot de passe aléatoire et l’affiche dans son journal
(docker logs artist-alley) ; voir
Première connexion.
Changez-le dès que vous êtes connecté.
Vos envois sont conservés à deux endroits, les enregistrements dans Postgres
et les fichiers dans le volume artist-alley-storage, et les clés de
artist-alley.env sont nécessaires pour les utiliser. Supprimer puis
recréer le conteneur ne pose aucun problème. Pour conserver ce que vous avez
envoyé, gardez les trois éléments ensemble ; l’un d’eux seul ne suffit pas
à restaurer une installation (Sauvegarde).
La configuration Docker Compose (et la compilation depuis les sources) se
trouve dans le guide d’installation.
Je veux l’installer pour une équipe
Section intitulée « Je veux l’installer pour une équipe »Lisez le guide d’installation : faites tourner l’image Docker publiée derrière votre reverse proxy existant pour le TLS. Le serveur lui-même parle en HTTP simple ; tout ce qui est accessible à d’autres personnes via un réseau doit donc passer par HTTPS. Épinglez une version précise plutôt qu’un tag mobile, afin qu’une mise à jour n’ait lieu que lorsque vous la décidez. La distribution se fait uniquement par Docker aujourd’hui ; des paquets natifs (.deb/.rpm, Homebrew) et des binaires autonomes sont prévus. Le guide Pour les opérateurs couvre la configuration de Postgres, les backends de stockage (système de fichiers ou tout bucket compatible S3), les sauvegardes et les mises à jour.
Je veux modifier le code
Section intitulée « Je veux modifier le code »Le développement local utilise Docker Compose, et la CI démarre le même
docker-compose.yml, avec un fichier de surcharge pour son runner partagé
qui supprime les ports de l’hôte et plafonne la mémoire.
Prérequis
Section intitulée « Prérequis »- Docker avec Docker Compose v2, Git et
openssl(le script d’amorçage s’en sert pour générer les secrets) - Assez d’espace disque libre pour Postgres et les fichiers que vous envoyez
- Des ports TCP libres pour le stack : par défaut 8088 (l’application, via nginx), 5173 (le serveur de développement Vite) et 5433 (Postgres)
Démarrer le stack
Section intitulée « Démarrer le stack »git clone https://github.com/Artist-Alley-Org/artist-alley.gitcd artist-alley./scripts/bootstrap.shscripts/bootstrap.sh crée .env à partir de .env.example, génère le mot
de passe Postgres et les deux clés requises (AA_SCRAMBLE_KEY et
AA_MASTER_KEY), puis construit et démarre le stack et attend un court
instant qu’il soit lancé. Il ne confirme pas que tout fonctionne
correctement ; les vérifications de la section Vérifier le stack ci-dessous
s’en chargent. Si un fichier .env existe déjà, le script n’y touche pas.
Copier .env.example à la main ne suffit pas : le serveur rejette au
démarrage sa clé maître factice, et les autres valeurs factices ne sont pas
des secrets.
L’application est servie via nginx à l’adresse
http://localhost:8088 (NGINX_HTTP_PORT dans
.env), et le serveur de développement Vite avec rechargement à chaud
tourne sur :5173. Le stack de développement définit
AA_BOOTSTRAP_DEFAULT_ADMIN=1 ; il crée donc admin avec le mot de passe
de développement public ArtistAlleyMogul ; ne définissez jamais cette
variable sur une installation réelle. Modifiez les fichiers Svelte dans
web/src/ et ils se rechargent à chaud ; modifiez les fichiers Go et
exécutez docker compose up -d --build pour reconstruire le conteneur de
l’application.
Vérifier le stack
Section intitulée « Vérifier le stack »# Postgres ready:docker compose exec -T postgres pg_isready -U artist_alley -d artist_alley
# Hit the Go health endpoint:curl -fsS http://localhost:8088/healthz
# Run the integration tests:./scripts/test.shLa CI exécute le même ./scripts/test.sh sur son stack Compose ; voir
.github/workflows/ci.yml.
Pour aller plus loin
Section intitulée « Pour aller plus loin »- Référence de l’API : le contrat de l’API, avec le format des requêtes et des réponses pour chaque opération.
- Architecture : comment le serveur, l’application web, Postgres et le stockage de fichiers s’articulent.
- Décisions d’architecture : le raisonnement derrière les grands choix.