Installer avec Docker Compose ou Portainer
KiwiDesk est livré sous forme d’images Docker prêtes à l’emploi, publiées sur le registre GitHub
ghcr.io/kaipicpic. L’installation consiste à décrire la configuration dans un fichier
d’environnement, puis à démarrer la stack. Comptez une quinzaine de minutes.
Ce que contient la stack
Section intitulée « Ce que contient la stack »Le fichier docker-compose.yml du dépôt démarre quatre services :
| Service | Image | Rôle |
|---|---|---|
postgres |
postgres:16-alpine |
La base de données, dans le volume postgres-data. |
api |
ghcr.io/kaipicpic/kiwidesk-api |
Le serveur (NestJS). Fichiers envoyés dans le volume uploads. |
web |
ghcr.io/kaipicpic/kiwidesk-web |
L’application que les postes ouvrent dans le navigateur. |
docs |
ghcr.io/kaipicpic/kiwidesk-docs |
Cette documentation (facultatif). |
Seul le service web est exposé sur le réseau (port 3000 par défaut). La base et l’API ne
répondent que sur 127.0.0.1 du serveur : les navigateurs passent toujours par web, qui relaie
les appels vers l’API.
-
Autoriser le serveur à télécharger les images. Tant que le dépôt est privé, créez sur GitHub un jeton (« Personal access token », classique) avec le seul droit
read:packages, puis connectez le serveur au registre :Fenêtre de terminal docker login ghcr.io -u <votre-identifiant-github>Collez le jeton quand le mot de passe est demandé. Dans Portainer, ajoutez plutôt le registre dans Registries > Add registry > Custom registry avec l’adresse
ghcr.io. -
Récupérer les fichiers. Il vous faut
docker-compose.ymlet.env.example, à la racine du dépôt. Placez-les dans un dossier dédié, par exemple/opt/kiwidesk, et copiez.env.exampleen.env. -
Générer les secrets. Trois valeurs doivent être uniques et aléatoires. Générez-les sur n’importe quelle machine qui a Node.js, ou avec OpenSSL :
Fenêtre de terminal # ENCRYPTION_KEY : 32 octets en base64openssl rand -base64 32# JWT_ACCESS_SECRET et JWT_REFRESH_SECRET : 64 octets, deux valeurs différentesopenssl rand -base64 64 | tr -d '\n=' | tr '+/' '-_'Choisissez aussi un mot de passe solide pour
POSTGRES_PASSWORD. -
Remplir le fichier
.env. Au minimum :NODE_ENV=productionAPP_PUBLIC_URL=https://kiwidesk.ma-boutique.frCORS_ORIGINS=https://kiwidesk.ma-boutique.frPOSTGRES_PASSWORD=<mot de passe de la base>ENCRYPTION_KEY=<clé générée>JWT_ACCESS_SECRET=<secret généré>JWT_REFRESH_SECRET=<autre secret généré>COOKIE_SECURE=trueSWAGGER_ENABLED=falseSEED_ADMIN_EMAIL=vous@ma-boutique.frSEED_STORE_NAME=Ma boutiqueCOOKIE_SECURE=truesuppose que KiwiDesk est servi en HTTPS ; laissezfalsepour un essai en HTTP sur le réseau local. Chaque variable est décrite dans Variables d’environnement. -
Démarrer la stack.
Depuis le dossier qui contient
docker-compose.ymlet.env:Fenêtre de terminal docker compose -f docker-compose.yml pulldocker compose -f docker-compose.yml up -dL’option
-f docker-compose.ymlest importante si vous avez cloné tout le dépôt : sans elle, Docker lit aussidocker-compose.override.yml, qui reconstruit les images depuis les sources au lieu de télécharger les images publiées.- Ouvrez Stacks > Add stack et nommez la stack
kiwidesk. - Choisissez Web editor et collez le contenu de
docker-compose.yml. - Sous Environment variables, cliquez sur Load variables from .env file et choisissez
votre fichier
.env, ou ajoutez les variables une par une. - Cliquez sur Deploy the stack.
Portainer ne lit que le fichier collé :
docker-compose.override.ymln’est jamais utilisé. - Ouvrez Stacks > Add stack et nommez la stack
-
Suivre le premier démarrage. Au démarrage, le conteneur
apiapplique les migrations de la base puis crée les données de départ (rôles, boutique, premier super administrateur) :Fenêtre de terminal docker compose -f docker-compose.yml logs -f apiAttendez la ligne
[seed] Done. Si vous avez laisséSEED_ADMIN_PASSWORDvide, le mot de passe du super administrateur est affiché une seule fois dans un cadre de ce journal : notez-le. -
Ouvrir KiwiDesk. Rendez-vous sur
http://<adresse-du-serveur>:3000, ou sur votre nom de domaine une fois le reverse proxy en place, et poursuivez avec le premier démarrage.
Résultat attendu
Section intitulée « Résultat attendu »docker compose -f docker-compose.yml ps montre les services postgres, api et web à l’état
running (healthy). L’adresse de KiwiDesk affiche la page de connexion.
Choisir une version
Section intitulée « Choisir une version »Par défaut, la stack suit la dernière version publiée (KIWIDESK_VERSION=latest). Pour figer
une version, indiquez un numéro de version (1.2.0) ou de commit (sha-1a2b3c4) dans
KIWIDESK_VERSION. Les images des services api et web doivent toujours porter la même
version. Voir Mises à jour et migrations.
Si ça ne marche pas
Section intitulée « Si ça ne marche pas »POSTGRES_PASSWORD is required(ouENCRYPTION_KEY,JWT_ACCESS_SECRET…) : la variable manque dans.envou dans les variables de la stack Portainer.deniedouunauthorizedau téléchargement des images : le serveur n’est pas connecté àghcr.io, ou le jeton n’a pas le droitread:packages.- Le service
apiredémarre en boucle : lisez son journal (docker compose logs api). Les causes les plus fréquentes sont décrites dans le dépannage. SEED_ADMIN_PASSWORD does not satisfy the password policy: le mot de passe fourni doit compter au moins 12 caractères et trois types parmi minuscules, majuscules, chiffres et symboles. Videz la variable pour qu’un mot de passe soit généré.