Déploiement de Docker Compose

Ce guide explique comment déployer HagiCode avec Docker Compose. Il convient aux serveurs, aux NAS, au partage en équipe ou aux cas nécessitant une isolation de l’environnement ; pour un usage personnel en local, privilégiez Microsoft Store ou Desktop.

Pourquoi choisir Docker Compose

• l’isolation de l’environnement réduit les conflits de dépendances
• la pile de services HagiCode actuellement prise en charge démarre en une seule fois
• la configuration, les mises à niveau et la maintenance suivent un chemin unifié
• l’hôte n’a besoin que de Docker, sans avoir à installer Node.js ou Git séparément

À propos du stockage des données par défaut

Les modèles Docker Compose actuellement pris en charge conservent les données via le chemin SQLite local par défaut. Dans la plupart des cas, vous n’avez pas besoin de provisionner un service de base de données distinct sur la machine hôte.

Tutoriel vidéo

Si vous souhaitez d’abord voir le flux complet, commencez par le didacticiel vidéo :

Regardez le tutoriel vidéo sur Bilibili

Le contenu vidéo comprend :

• Démonstration complète du processus de déploiement de Docker Compose
• Instructions de génération et de modification du fichier de configuration
• Étapes de démarrage et de vérification du service
• Problèmes courants et solutions

Durée de la vidéo : environ 15 minutes

Conditions préalables

Avant de commencer, assurez-vous que Docker et Docker Compose sont installés sur votre système.

Installer Docker

Windows

Téléchargez et installez Docker Desktop pour Windows. Une fois l’installation terminée, assurez-vous que Docker Desktop est en cours d’exécution.

macOS

Téléchargez et installez Docker Desktop pour Mac. Une fois l’installation terminée, assurez-vous que Docker Desktop est en cours d’exécution.

Linux

Installez Docker Engine et le plugin Docker Compose en suivant la documentation officielle de Docker pour votre distribution : Install Docker Engine. Les dépôts de paquets et les noms de paquets varient d’une distribution à l’autre ; n’appliquez donc pas telles quelles les commandes d’une autre distribution.

Une fois l’installation terminée, démarrez le service Docker et activez son démarrage automatique :

sudo systemctl start docker
sudo systemctl enable docker

Vérifier l’installation

Une fois l’installation terminée, exécutez les commandes suivantes pour vérifier que Docker et Docker Compose sont correctement installés :

docker --version
docker compose version

Démarrage rapide

1. Générer le fichier de configuration Docker Compose

Utilisez Docker Compose Builder pour générer docker-compose.yml. Il s’agit d’un site autonome : ses règles de génération et ses mises à jour font foi.

Le générateur prend en charge :

• le choix du fournisseur d’API (Zhipu AI, Anthropic officiel, API personnalisée), avec configuration de l’URL de l’API et du jeton
• des ports, noms de conteneurs, répertoires de persistance et répertoires de travail personnalisés
• le choix d’une base de données intégrée ou externe
• la gestion automatique des différences entre les plateformes Windows / Linux et des problèmes courants de permissions de fichiers
• l’utilisation d’une image Docker Hub prise en charge

Étapes :

1. Ouvrez Docker Compose Builder.
2. Remplissez la configuration selon vos besoins : choisissez le fournisseur d’API, configurez les ports, la base de données, le répertoire de travail et les autres options.
3. Cliquez sur le bouton de génération pour obtenir la configuration docker-compose.yml.
4. Enregistrez la configuration générée dans un fichier docker-compose.yml.
5. Si nécessaire, créez un fichier .env pour les informations sensibles, afin de ne pas écrire le jeton directement dans le fichier compose.

Source de l’image

Le générateur utilise Docker Hub comme source d’image prise en charge :

• Adresse de l’image : newbe36524/hagicode:{tag}
• Scénarios applicables : convient aux utilisateurs disposant d’une accélération de miroir Docker Hub
• Remarques : une accélération de miroir peut devoir être configurée dans certaines régions

Obtenir un jeton d’API

Le déploiement Docker accède aux modèles via le fournisseur d’API configuré dans le générateur ; vous devez donc d’abord disposer d’un jeton d’API valide :

Zhipu AI : Obtenir un jeton d’API →

• Accès stable depuis la Chine, réponses plus rapides
• Bon rapport qualité-prix, adapté à un usage quotidien

Anthropic officiel : Obtenir un jeton d’API →

• Utilisation directe des services d’Anthropic

Vous pouvez aussi choisir une API personnalisée dans le générateur.

2. Démarrer les services

Exécutez la commande suivante dans le répertoire où se trouve docker-compose.yml :

docker compose up -d

Cette commande va :

• télécharger et démarrer les conteneurs HagiCode définis dans la configuration générée
• créer et configurer le réseau
• initialiser le répertoire de données par défaut et les dépendances d’exécution

3. Vérifier l’état du service

Vérifiez que les conteneurs sont en cours d’exécution :

docker compose ps

Vous devriez voir les services définis dans la configuration générée à l’état « running ».

Consultez les journaux du service :

# Afficher les journaux de tous les services
docker compose logs

# Afficher les journaux du service HagiCode
docker compose logs hagicode

# Suivre les journaux en temps réel
docker compose logs -f hagicode

Accéder à l’application

Une fois le service démarré avec succès, accédez-y depuis votre navigateur :

http://localhost:45000

Si vous avez modifié le port dans le générateur, utilisez le port hôte que vous avez défini. À la première ouverture, vous arrivez sur l’assistant d’initialisation ; poursuivez avec l’Assistant de configuration.

Instructions de configuration

Si vous devez modifier la configuration (par exemple changer de port ou de fournisseur d’API), vous pouvez :

1. Régénérer une nouvelle configuration avec Docker Compose Builder
2. Modifier manuellement les fichiers docker-compose.yml et .env
3. Recréer les conteneurs pour que la configuration prenne effet :

docker compose up -d

docker compose restart ne fait que redémarrer les conteneurs existants et n’applique pas les modifications de docker-compose.yml ou .env. Après avoir modifié la configuration, utilisez docker compose up -d.

Persistance des données

Le chemin Docker Compose actuellement pris en charge utilise par défaut des fichiers de données SQLite avec des volumes persistants. Si vous devez vérifier l’emplacement des montages ou planifier des sauvegardes, consultez directement les mappages de volumes et de répertoires de données dans le fichier docker-compose.yml généré.

Maintenance courante

Arrêt et démarrage

# Arrêter les services (conteneurs et données conservés)
docker compose stop

# Les redémarrer
docker compose start

# Arrêter et supprimer les conteneurs (les volumes de données sont conservés)
docker compose down

N’ajoutez pas -v à docker compose down à la légère : cette option supprime aussi les volumes de données déclarés dans le fichier compose.

Mettre à niveau

1. Avant la mise à niveau, sauvegardez le répertoire de données (voir ci-dessous).
2. Remplacez dans docker-compose.yml l’étiquette d’image newbe36524/hagicode:{tag} par la version cible, ou régénérez la configuration avec le générateur.
3. Récupérez la nouvelle image et recréez les conteneurs :

docker compose pull
docker compose up -d

Sauvegarder les données

Exécutez d’abord docker compose stop pour que le service cesse d’écrire, sauvegardez ensuite les répertoires ou volumes de données correspondant aux mappages de volumes et de répertoires de données de docker-compose.yml, puis exécutez docker compose start pour relancer le service.

Étapes suivantes

Vous avez maintenant déployé HagiCode avec succès. Ensuite :

1. Lisez l’Assistant de configuration pour créer le Hagicoder par défaut et votre premier projet.
2. Dans Créer une session de conversation, commencez par explorer le projet en mode lecture seule, puis passez si besoin à Créer une session de proposition.

Si vous préférez l’application de bureau, consultez l’Installation de bureau.