Aller au contenu

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.

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.

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

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_PASSWORD=your-db-password \
-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 à 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.

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.

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.

  • 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)
Fenêtre de terminal
git clone https://github.com/Artist-Alley-Org/artist-alley.git
cd artist-alley
./scripts/bootstrap.sh

scripts/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.

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

La CI exécute le même ./scripts/test.sh sur son stack Compose ; voir .github/workflows/ci.yml.