Aller au contenu

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.

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.

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

  2. Récupérer les fichiers. Il vous faut docker-compose.yml et .env.example, à la racine du dépôt. Placez-les dans un dossier dédié, par exemple /opt/kiwidesk, et copiez .env.example en .env.

  3. 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 base64
    openssl rand -base64 32
    # JWT_ACCESS_SECRET et JWT_REFRESH_SECRET : 64 octets, deux valeurs différentes
    openssl rand -base64 64 | tr -d '\n=' | tr '+/' '-_'

    Choisissez aussi un mot de passe solide pour POSTGRES_PASSWORD.

  4. Remplir le fichier .env. Au minimum :

    NODE_ENV=production
    APP_PUBLIC_URL=https://kiwidesk.ma-boutique.fr
    CORS_ORIGINS=https://kiwidesk.ma-boutique.fr
    POSTGRES_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=true
    SWAGGER_ENABLED=false
    SEED_ADMIN_EMAIL=vous@ma-boutique.fr
    SEED_STORE_NAME=Ma boutique

    COOKIE_SECURE=true suppose que KiwiDesk est servi en HTTPS ; laissez false pour un essai en HTTP sur le réseau local. Chaque variable est décrite dans Variables d’environnement.

  5. Démarrer la stack.

    Depuis le dossier qui contient docker-compose.yml et .env :

    Fenêtre de terminal
    docker compose -f docker-compose.yml pull
    docker compose -f docker-compose.yml up -d

    L’option -f docker-compose.yml est importante si vous avez cloné tout le dépôt : sans elle, Docker lit aussi docker-compose.override.yml, qui reconstruit les images depuis les sources au lieu de télécharger les images publiées.

  6. Suivre le premier démarrage. Au démarrage, le conteneur api applique 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 api

    Attendez la ligne [seed] Done. Si vous avez laissé SEED_ADMIN_PASSWORD vide, le mot de passe du super administrateur est affiché une seule fois dans un cadre de ce journal : notez-le.

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

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.

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.

  • POSTGRES_PASSWORD is required (ou ENCRYPTION_KEY, JWT_ACCESS_SECRET…) : la variable manque dans .env ou dans les variables de la stack Portainer.
  • denied ou unauthorized au téléchargement des images : le serveur n’est pas connecté à ghcr.io, ou le jeton n’a pas le droit read:packages.
  • Le service api redé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é.