> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://documentation.celestory.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🔒Celestory & Voltask auto-hébergé

# **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)](#4-configuration--la-proc%C3%A9dure-pas-%C3%A0-pas).
## **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](#42-les-variables-%C3%A0-r%C3%A9gler)).
### **🛡️ `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**
| **Conteneur** | **Rôle (en clair)** |
| ---- |
| `celestory-gateway` | 🚪 Le portier — **seul point d'entrée**, publie l'interface sur le port **1500** |
| `celestory-frontend` | 🖥️ L'interface web que tu vois |
| `celestory-api` | ⚙️ Le cerveau applicatif (cloud API) |
| `celestory-auth` | 🔑 La connexion / les comptes (OAuth, jetons) |
| `celestory-hub` | 📜 La gestion de **licence** (et l'admin) |
| `celestory-voltask` | 🤖 Le moteur d'**automatisation** Voltask |
| `celestory-orchestrator` | 🎬 Coordonne les tâches Voltask |
| `celestory-generator` | 🏗️ Génère les projets / fichiers |
| `celestory-db` | 🗄️ La base de données PostgreSQL (toutes les données) |
| `celestory-plugins-bun` | 🔌 Plugins (runtime Bun) |
| `celestory-plugins-deno` | 🔌 Plugins (runtime Deno) |
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](#7-d%C3%A9pannage--les-pi%C3%A8ges-courants)).
## **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](https://celestory.io/pricing)).
* Une **clé API fal.ai** si tu veux les fonctions de génération par IA (voir [`FAL_API_KEY`](#43--variable-fal_api_key-g%C3%A9n%C3%A9ration-ia)).
## **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 :
| **Situation** | **Ton URL d'accès (« BASE »)** |
| ---- |
| Accès local, sur la machine elle-même | `http://localhost:1500` |
| Accès depuis le réseau, par IP | `http://192.168.x.x:1500` |
| Accès par un nom de domaine derrière un reverse proxy avec HTTPS | `https://celestory.mondomaine.com` (souvent **sans** `:1500`, car le proxy gère le port) |
> 📌 **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](#%EF%B8%8F-origin-et-la-protection-csrf--le-point-critique).)
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 :
| **Conteneur** | **Variable** | **Valeur (remplace `BASE` par ton URL)** |
| ---- |
| `api` | `ORIGIN` | **`BASE/celestory/api`** |
| `auth` | `SELF_HOSTED_REDIRECT_URI` | **`BASE/celestory/callback`** |
| `hub` | `ORIGIN` | **`BASE/hub`** |
| `voltask` | `WEBHOOK_URL` | **`BASE/voltask`** |
**Exemple concret avec `BASE = http://localhost:1500` :**
| **Conteneur** | **Variable** | **Valeur à saisir** |
| ---- |
| `api` | `ORIGIN` | `http://localhost:1500/celestory/api` |
| `auth` | `SELF_HOSTED_REDIRECT_URI` | `http://localhost:1500/celestory/callback` |
| `hub` | `ORIGIN` | `http://localhost:1500/hub` |
| `voltask` | `WEBHOOK_URL` | `http://localhost:1500/voltask` |
> ⚠️ **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](https://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](#7-d%C3%A9pannage--les-pi%C3%A8ges-courants).)
## **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](#42-les-variables-%C3%A0-r%C3%A9gler). 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](https://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.
| **Symptôme** | **Cause** | **Solution** |
| ---- |
| **Login impossible**, erreur `{"message":"Cross-site POST form submissions are forbidden"}` **403** | L'URL d'accès ≠ la variable `ORIGIN` (protocole, nom **ou port** différent) | Aligner `ORIGIN`/`REDIRECT`/`WEBHOOK` **exactement** sur l'URL de la barre d'adresse (cf. [4.1](#41-le-principe--choisir-ton-adresse-dacc%C3%A8s-une-fois-pour-toutes)). `http`≠`https`, et `:1500` compte ! |
| **La stack ne démarre pas** : `hub` en `unhealthy`, et `api`/`frontend`/`generator`/`voltask`/`gateway` figés en `Created` | Le hub a `PORT = 1500` au lieu de `1402` → son contrôle de santé échoue en boucle → bloque tous les services qui l'attendent | `sudo sed -i 's\ | PORT: "1500"\ | PORT: "1402"\ | ' "$COMPOSE"` puis recréer (cf. [4.5](#45-%EF%B8%8F-v%C3%A9rifier-le-port-interne-du-hub-port--1402)) |
| `dependency failed to start: container celestory-hub is unhealthy` | Même cause que ci-dessus | Idem |
| `unknown shorthand flag: 'd' in -d` | La variable `$COMPOSE` est **vide** (nouvelle session terminal) | Retaper la ligne `COMPOSE=/var/lib/...` puis relancer |
| `Permission denied` en lisant le compose | Il faut les droits root | Préfixer la commande par `sudo` |
| Bandeau CasaOS **« Installing NaN% / Error »** | Désynchro de l'UI CasaOS après une recréation en ligne de commande | **Cosmétique** : fermer avec ✕. Ne **pas** réinstaller (ça écraserait tes corrections) |
| Login OK mais une fonction de **génération IA** ne marche pas | `FAL_API_KEY` absente ou invalide | Ajouter la clé fal.ai (cf. [4.3](#43--variable-fal_api_key-g%C3%A9n%C3%A9ration-ia)) |
| Connexion avec un email admin refusée alors que ça marche sur une autre machine | L'admin a été *seedé* avec un **autre** email au 1er démarrage | Se connecter avec l'email d'origine de **cette** machine |
### **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.

*