Guide complet — Auto-héberger Celestory & Voltask sur CasaOS

Guide d'installation et de configuration de Celestory & Voltask sur CasaOS (l'OS du Celestory Kubb), pensé pour les personnes non développeuses : chaque concept est expliqué, chaque réglage est justifié, et tous les pièges courants sont couverts.

0. À qui s'adresse ce guide ?

À toute personne qui veut installer Celestory & Voltask « chez soi » (sur son propre serveur) via CasaOS, sans être développeur. On explique tout : ce qu'est un conteneur, une variable d'environnement, un port, etc. Si tu connais déjà ces notions, saute directement à la section 4 (configuration).

1. Les concepts de base (à lire une fois)

Avant de toucher quoi que ce soit, voici les 7 notions qui reviennent tout le temps. Comprendre ça t'évitera 90 % des galères.

🧱 Un « conteneur » (container)

Imagine une petite boîte étanche qui contient un programme et tout ce dont il a besoin pour tourner (sa version de Node, ses fichiers, ses réglages). C'est isolé du reste de la machine. Celestory n'est pas un programme : c'est 11 conteneurs qui travaillent ensemble (l'API, la base de données, l'authentification, etc.). C'est ce qu'on appelle une stack (une « pile » de services).

🐳 Docker

C'est le moteur qui fait tourner ces boîtes. CasaOS s'appuie dessus.

📋 Le fichier docker-compose.yml

C'est la recette de la stack : il liste les 11 conteneurs, leurs réglages, comment ils se parlent. Sur CasaOS, il se trouve ici :

/var/lib/casaos/apps/big-bear-celestory-voltask/docker-compose.yml

👉 Tout ce qu'on va régler dans ce guide, c'est ce fichier (soit via l'interface CasaOS, soit en ligne de commande).

🔧 Une « variable d'environnement »

C'est un réglage passé à un conteneur sous forme NOM = valeur. Par exemple ADMIN_PASSWORD = password. Le programme lit ces variables au démarrage pour savoir comment se comporter. C'est l'essentiel de ce qu'on va modifier.

🔌 Un « port »

Une machine peut faire tourner plusieurs services en même temps ; le port est le « numéro de porte » qui dit à quel service on veut parler. Exemples : un site web classique = porte 80 (http) ou 443 (https). Celestory expose son interface sur la porte 1500. Deux types de ports à ne pas confondre :

• port interne : utilisé à l'intérieur de la boîte (entre conteneurs) ;
• port publié : la porte ouverte vers l'extérieur, celle que tu tapes dans ton navigateur.

🚪 Le « gateway » (passerelle / reverse proxy)

Un des 11 conteneurs s'appelle celestory-gateway. C'est le portier de la stack : c'est le seul point d'entrée. Quand tu ouvres l'interface, tu parles au gateway, et lui redistribue vers le bon service selon le chemin de l'URL :

• …/celestory/api → va vers l'API
• …/hub → va vers le Hub (gestion de licence)
• …/voltask → va vers Voltask (le moteur d'automatisation)

C'est exactement pour ça que les chemins dans les URL comptent (voir section 4.2).

🛡️ ORIGIN et la protection « CSRF » — LE point critique

Le hub et l'auth de Celestory sont bâtis avec un framework (SvelteKit) qui a une sécurité anti-piratage appelée protection CSRF. En résumé :

Le serveur refuse toute action sensible (comme le login) si l'adresse depuis laquelle tu l'envoies ne correspond pas exactement à l'adresse déclarée dans la variable ORIGIN.

« Exactement » veut dire : même protocole (http vs https), même nom (localhost vs un domaine), même port (:1500). La moindre différence = erreur :

{"message":"Cross-site POST form submissions are forbidden"}  ← erreur 403

👉 Règle d'or de tout ce guide : la variable ORIGIN (et ses sœurs) doit être identique, caractère pour caractère, à l'URL que tu tapes dans la barre d'adresse de ton navigateur. C'est la cause n°1 des échecs de connexion.

2. Vue d'ensemble : les 11 conteneurs

Ils démarrent dans l'ordre : la plupart attendent que celestory-hub soit « en bonne santé » (healthy) avant de démarrer. Si le hub ne démarre pas, toute la stack reste bloquée (voir dépannage).

3. Prérequis

• CasaOS installé et fonctionnel (ici : sur le Celestory Kubb sous WSL2 + Docker natif, mais ça marche pareil sur un vrai serveur Linux).
• L'application « Celestory & Voltask » (big-bear-celestory-voltask) installée depuis le store CasaOS.
• Savoir ouvrir le terminal de CasaOS (ou se connecter en SSH).
• Une licence Celestory (l'offre est payante, pas de version gratuite — voir celestory.io/pricing).
• Une clé API fal.ai si tu veux les fonctions de génération par IA (voir FAL_API_KEY).

4. Configuration — la procédure pas à pas

4.1 Le principe : choisir ton « adresse d'accès » une fois pour toutes

Avant de remplir quoi que ce soit, décide par quelle URL tu vas accéder à Celestory. Cette URL sera réutilisée partout. Deux cas typiques :

📌 Le port :1500 fait partie de l'adresse. L'interface est servie sur le port publié 1500. Si tu y accèdes par ce port, alors l'adresse va jusqu'au port — exemple concret d'une vraie page : http://localhost:1500/hub/licenses. Si ta barre d'adresse affiche :1500, alors toutes tes variables doivent contenir :1500. (Rappelle-toi la règle d'or de la section 1.)

Dans la suite, on note BASE ton URL d'accès. Exemple : BASE = http://localhost:1500.

4.2 Les variables à régler

Le gateway redistribue selon le chemin de l'URL. Il faut donc renseigner les chemins complets dans chaque variable :

Exemple concret avec BASE = http://localhost:1500 :

⚠️ Cohérence du protocole. Si tu accèdes en http://, tout doit être en http://. Si tu accèdes en https://, tout en https://. Un mélange = erreur 403 au login (la fameuse protection CSRF).

4.3 🆕 Variable FAL_API_KEY (génération IA)

C'est quoi ? fal.ai est un service en ligne qui exécute des modèles d'IA (génération d'images, etc.). Celestory l'utilise pour ses fonctions de génération par IA. Sans cette clé, ces fonctions ne marchent pas.

Comment l'obtenir ? Crée un compte sur fal.ai → section API Keys → génère une clé (elle ressemble à une longue suite de caractères).

Où l'ajouter ? Ajoute une variable d'environnement :

FAL_API_KEY = ta_clé_fal_ai_ici

sur le service qui fait la génération (typiquement generator, et/ou api selon ta version). Dans le doute, ajoute-la aux deux — une variable en trop est inoffensive.

4.4 🗑️ Les volumes projectFiles : inutiles

Rappel : c'est quoi un volume ? Un conteneur est « étanche » : ce qu'il écrit dedans disparaît s'il est recréé. Un volume est un dossier partagé entre l'intérieur du conteneur et le disque de la machine hôte, pour conserver les fichiers.

👉 Dans la version actuelle, les volumes projectFiles (côté api et generator) ne sont pas nécessaires. Si ton install en possède, tu peux les retirer sans rien casser ; et si tu pars de zéro, inutile de les ajouter.

4.5 ⚙️ Vérifier le port interne du Hub (PORT = 1402)

Sur certaines versions de l'image, le hub est livré avec un mauvais port interne qui empêche toute la stack de démarrer (le hub reste « unhealthy », et tous les autres conteneurs restent bloqués en Created).

Le hub doit avoir :

PORT = 1402

(et non 1500 — 1500 est le port publié par le gateway, pas le port interne du hub). Le gateway, lui, cherche le hub sur HUB_PORT = 1402, et le contrôle de santé teste aussi 1402. Si tu vois PORT = 1500 dans le bloc hub, corrige-le en 1402. (Détails et symptômes en section 7.)

5. Où et comment modifier ces réglages ?

Deux méthodes. Choisis-en une.

Méthode A — via l'interface CasaOS (recommandée pour les non-devs)

1. Ouvre CasaOS → clique sur l'app Celestory & Voltask → ⚙️ Paramètres.
2. En haut, des onglets : api, auth, db, frontend, gateway, generator, hub, … Clique sur le service voulu.
3. Descends à « Variables d'environnement ». Modifie la Valeur en face de la bonne Clé, ou clique + Ajouter pour FAL_API_KEY.
4. Pour retirer un volume : section « Volumes » → clique sur la croix ✕ de la ligne.
5. Enregistre → CasaOS recrée la stack automatiquement.

⚠️ Deux pièges de l'interface CasaOS :Après enregistrement, vérifie que le hub a toujours PORT = 1402 (l'UI peut parfois le réafficher) — sinon corrige-le avant de sauvegarder.Un bandeau « Installing NaN% / Error » peut apparaître : c'est purement cosmétique quand la stack a aussi été touchée en ligne de commande. Ferme-le avec la croix ✕, ne clique pas sur « réinstaller ».

Méthode B — en ligne de commande (plus rapide, plus sûr)

Ouvre le terminal CasaOS (ou SSH). On définit d'abord un raccourci vers le fichier, et on fait une sauvegarde :

COMPOSE=/var/lib/casaos/apps/big-bear-celestory-voltask/docker-compose.yml
sudo cp $COMPOSE ${COMPOSE}.bak.$(date +%Y%m%d_%H%M%S)

🧠 Deux choses à savoir absolument :La variable COMPOSE=… disparaît si tu fermes/rouvres le terminal (nouvelle session). Si une commande $COMPOSE te renvoie une erreur bizarre (unknown shorthand flag: 'd'), c'est qu'elle est vide → retape la ligne COMPOSE=….Lire ou modifier ce fichier nécessite sudo (sinon : Permission denied).

Exemple : corriger le port du hub et vérifier les réglages actuels :

# 1) Corriger le port interne du hub (1500 → 1402) — sans risque, 1500 n'existe que là
sudo sed -i 's|PORT: "1500"|PORT: "1402"|' "$COMPOSE"
​
# 2) Vérifier les origines / chemins / clé
sudo grep -nE 'ORIGIN|WEBHOOK|REDIRECT|FAL_API_KEY' "$COMPOSE"

Pour les origines/chemins, le plus sûr est d'éditer le fichier (avec sudo nano "$COMPOSE") et de mettre les valeurs exactes du tableau 4.2. Repère chaque bloc de service (api:, auth:, hub:, voltask:) et corrige la ligne sous environment:.

Une fois les modifs faites, applique-les en recréant la stack :

sudo docker compose -f "$COMPOSE" up -d --force-recreate

Puis surveille le démarrage (Ctrl+C pour quitter la surveillance) :

watch -n3 'sudo docker ps --filter "name=celestory" --format "table {{.Names}}\t{{.Status}}"'

🎯 Objectif : les 11 conteneurs en healthy. Le hub doit passer healthy en 30–60 s, puis les autres démarrent en cascade.

6. Première connexion & activation de la licence

6.1 Se connecter au Hub

1. Ouvre exactement ton URL BASE dans le navigateur (ex. http://localhost:1500).

• • En https avec certificat auto-signé : le navigateur affiche un avertissement → Avancé → Continuer, c'est normal.

2. Page de login CELESTORY HUB. Identifiants par défaut (définis dans le bloc hub du compose) :

• • Email : ADMIN_USERNAME (par défaut demo@mail.com)
  • Mot de passe : ADMIN_PASSWORD (par défaut password)

🧠 Concept important — le compte admin est créé UNE SEULE FOIS.
Le compte administrateur est inscrit dans la base de données au tout premier démarrage, à partir de la valeur qu'avait ADMIN_USERNAME à ce moment-là. Si tu changes ADMIN_USERNAME après coup, ça ne renomme pas le compte existant : connecte-toi avec l'email d'origine. Pour vraiment changer l'admin, il faut le modifier dans la base (ou réinitialiser la base — destructif).

6.2 Activer la licence

1. Une fois connecté, va sur la page des licences : BASE/hub/licenses

(ex. http://localhost:1500/hub/licenses).

2. Saisis ta clé de licence Celestory (achetée sur celestory.io/pricing).
3. Le hub valide la licence → les fonctions Voltask/Celestory se débloquent.

7. Dépannage — les pièges courants

Tableau des symptômes réels rencontrés lors d'une vraie install, avec la solution.

Commandes de diagnostic utiles

# État de tous les conteneurs
sudo docker ps -a --filter "name=celestory" --format "table {{.Names}}\t{{.Status}}"

# Sur quel port le hub écoute réellement (doit afficher 1402)
sudo docker logs --tail 20 celestory-hub

# Vérifier les origines/chemins/clé configurés
sudo grep -nE 'ORIGIN|WEBHOOK|REDIRECT|FAL_API_KEY|PORT: "14' "$COMPOSE"

# Logs d'auth (utile si le login échoue côté serveur)
sudo docker logs --tail 40 celestory-auth

8. Référence — valeurs finales d'exemple (BASE = http://localhost:1500)

# --- api ---
ORIGIN = http://localhost:1500/celestory/api
SELF_HOSTED = true
FAL_API_KEY = <ta_clé_fal_ai>            # selon version

# --- auth ---
SELF_HOSTED_REDIRECT_URI = http://localhost:1500/celestory/callback
USE_SELF_HOSTED_CLIENT = true

# --- hub ---
ORIGIN = http://localhost:1500/hub
PORT = 1402                               # ⚠️ surtout pas 1500
ADMIN_USERNAME = demo@mail.com            # ou ton email admin
ADMIN_PASSWORD = password                 # à changer en prod !

# --- voltask ---
WEBHOOK_URL = http://localhost:1500/voltask

# --- generator ---
FAL_API_KEY = <ta_clé_fal_ai>            # selon version

# --- gateway ---
# publie l'interface sur le port 1500 (ne pas changer HUB_PORT = 1402)

🔐 En production, change impérativement ADMIN_PASSWORD, le mot de passe PostgreSQL, et n'expose pas l'interface en http sur Internet sans reverse proxy + HTTPS.

Mis à jour le : 11/06/2026