Référence du Manifeste nekristo.yml

Ce document décrit toutes les options disponibles pour le fichier nekristo.yml, qui est la "source de vérité" pour chaque application au sein de la plateforme Nekristo.

Structure Globale

# Obligatoire. Nom unique de l'application.
# Doit correspondre exactement au nom du dossier dans apps/.
app_name: mon-super-crm

# Version de l'application ou du manifeste (pour information).
version: '1.0'

# Optionnel. Liste des *autres applications* de la plateforme dont celle-ci dépend.
# 'nekristo-cli apps start mon-super-crm' démarrera automatiquement ces dépendances.
app_dependencies:
  - autre-app-api # Exemple : 'mon-super-crm' dépend de 'autre-app-api'

# Optionnel. Liste des services d'infrastructure partagée requis.
# Valeurs possibles : 'database', 'cache', 'messaging', 'monitoring'.
# 'nekristo-cli apps start' s'assurera que ces services (définis dans platform.yml)
# sont démarrés avant de lancer l'application.
infra_dependencies:
  - database
  - cache

# Obligatoire. Liste contenant la définition d'au moins un composant.
components:
  - # ... voir la section ci-dessous ...

# Optionnel. Section pour la configuration des tests automatisés.
tests:
  # ... voir la section ci-dessous ...

La Section `components`

C'est une liste d'objets YAML, où chaque objet représente une unité logique et déployable de votre application (une API backend, une interface frontend, un worker, etc.).

Clé	Type	Oblig.	Description
`name`	`string`	Oui	Nom unique du composant au sein de l'application (ex: `backend`, `frontend`, `worker`). Utilisé pour nommer les services Docker et les conteneurs.
`path`	`string`	Oui	Chemin relatif (depuis la racine de l'application) vers le code source et le contexte de build Docker de ce composant (ex: `./`, `./backend`, `./services/worker`).
`type`	`string`	Non	Technologie principale (`python`, `nodejs`, etc.). Utilisé pour sélectionner un template `Dockerfile.<type>.tpl` si la clé `dockerfile` n'est pas spécifiée.
`dockerfile`	`string`	Non	Chemin relatif (depuis `path`) vers un `Dockerfile` personnalisé. Si présent, il a la priorité sur la clé `type` pour la construction de l'image.
`build_command`	`string`	Non	Commande à exécuter pendant le build Docker (dans les templates `Dockerfile.*.tpl`) pour compiler ou préparer le code (ex: `npm run build`, `mvn package`).
`run_command`	`string`	Oui	Commande pour lancer le service en production (ex: `uvicorn main:app --host 0.0.0.0`, `node dist/main.js`, `java -jar app.jar`).
`build_args`	`object`	Non	Dictionnaire de variables (clé: valeur) à passer comme arguments (`--build-arg`) lors de la construction de l'image Docker.
`environment`	`object`	Non	Dictionnaire de variables d'environnement non sensibles à injecter dans le conteneur pour tous les environnements (ex: `NODE_ENV: production`, `LOG_LEVEL: info`).
`public_port`	`integer`	Non	Port interne sur lequel le conteneur écoute et qui doit être exposé au reverse proxy (Nginx Proxy Manager). Nécessaire si le service doit être accessible via un domaine.
`local_domain`	`string`	Non	Domaine à utiliser pour accéder à ce composant en développement local (ex: `app.127.0.0.1.nip.io`). Requiert `public_port`. Utilisé par `platform setup-proxy`.
`public_domain`	`string`	Non	Domaine public à utiliser pour accéder à ce composant en production/staging (ex: `app.nekristo.com`). Requiert `public_port`. Déclenche la configuration du proxy distant par la CI.
`letsencrypt`	`boolean`	Non	Si `true` (et si `public_domain` est défini), demande à la CI (`ci setup-proxies`) de configurer Nginx Proxy Manager pour obtenir/renouveler un certificat SSL Let's Encrypt. Défaut : `false`.
`healthcheck`	`object`	Non	Configuration pour la vérification de santé Docker du conteneur (voir sous-section).
`database`	`object`	Non	Indique que ce composant a besoin d'une base de données PostgreSQL dédiée (voir sous-section).
`required_secrets`	`list[string]`	Non	Nouveau ! Liste des noms de variables d'environnement sensibles que ce composant attend. Utilisé par `secrets edit` pour s'assurer que ces clés existent dans les fichiers secrets avec une valeur (même "TODO"). Ex: `["STRIPE_KEY", "SENDGRID_API_KEY"]`.
`development`	`object`	Non	Paramètres spécifiques pour l'environnement de développement local (`nekristo-cli apps start`, voir sous-section).
`deployment`	`object`	Oui	Contient les informations pour le déploiement en production/staging (voir sous-section).

Sous-section `healthcheck`

Définit comment Docker doit vérifier si le conteneur est opérationnel. Requiert généralement que public_port soit défini pour utiliser curl.

Clé	Type	Oblig.	Description
`path`	`string`	Oui	Le chemin HTTP à interroger (doit commencer par `/`, ex: `/health`, `/status`).
`interval`	`string`	Non	Intervalle entre les vérifications (ex: `30s`, `1m`). Défaut Docker : `30s`.
`timeout`	`string`	Non	Temps d'attente maximum pour une réponse (ex: `5s`, `10s`). Défaut Docker : `30s`.
`retries`	`integer`	Non	Nombre d'échecs consécutifs avant de marquer comme `unhealthy`. Défaut Docker : `3`.
`start_period`	`string`	Non	Temps à attendre après le démarrage avant la première vérification (ex: `15s`). Défaut : `0s`.

Sous-section `database`

Indique qu'un composant nécessite une base de données PostgreSQL dédiée, gérée par l'infrastructure partagée.

Clé	Type	Oblig.	Description
`name`	`string`	Oui	Le nom de base de la base de données (ex: `crm_db`). Le nom final sera automatiquement suffixé par l'environnement (`crm_db_staging`, `crm_db_production`), sauf pour `dev`.
`migration_command`	`string`	Non	Commande à exécuter (dans le conteneur) pour appliquer les migrations BDD (ex: `alembic upgrade head`, `mvn flyway:migrate`). Utilisée par `apps db migrate` et potentiellement `pre_deploy`.
`seeding_command`	`string`	Non	Commande à exécuter pour peupler la BDD avec des données initiales (ex: `python seed.py`). Utilisée par `apps db seed`.

Note : La variable d'environnement DATABASE_URL est automatiquement injectée dans le conteneur si cette section est présente.

Sous-section `development`

Paramètres spécifiques utilisés uniquement lors de l'exécution avec nekristo-cli apps start.

Clé	Type	Oblig.	Description
`run_command`	`string`	Non	Surcharge la `run_command` principale pour le mode développement. Idéal pour activer le hot-reloading (ex: `uvicorn main:app --host 0.0.0.0 --reload`, `npm run dev`).
`volumes`	`list`	Non	Liste de volumes à monter au format Docker Compose (ex: `["./backend:/app"]`). Typiquement utilisé pour monter le code source local dans le conteneur et permettre le hot-reloading lors des modifications de fichiers.
`build_target`	`string`	Non	Nouveau ! Spécifie le "stage" cible d'un `Dockerfile` multi-stage à utiliser pour le développement (ex: `builder`). Très utile pour utiliser un stage de build Node.js (avec `npm`) pour le dev, tout en gardant un stage Nginx pour la prod.

Sous-section `deployment`

Paramètres utilisés par la CI/CD (nekristo-cli ci deploy).

Clé	Type	Oblig.	Description
`image_name`	`string`	Non	Nom complet de l'image Docker à utiliser pour le déploiement (ex: `ghcr.io/mon-org/mon-app-backend`). Si omis, généré par défaut : `<registry_prefix>/<app_name>-<component_name>`.
`restart`	`string`	Non	Politique de redémarrage Docker (ex: `unless-stopped`, `always`). Défaut : `unless-stopped`.
`strategy`	`string`	Non	Stratégie de déploiement. Peut être `blue-green` (nécessite `public_domain` et configuration NPM) ou `rolling` (mise à jour standard, par défaut).
`hooks`	`object`	Non	Commandes à exécuter à des moments clés du déploiement (voir sous-section).

Sous-section `hooks` (dans `deployment`)

Permet d'exécuter des commandes spécifiques pendant le processus de déploiement par la CI.

Clé	Type	Oblig.	Description
`pre_deploy`	`string`	Non	Commande à exécuter (dans un conteneur basé sur la nouvelle image) avant le démarrage ou le basculement du trafic vers le nouveau service. Typiquement utilisé pour les migrations BDD (ex: `alembic upgrade head`).

La Section `tests`

Section optionnelle pour définir comment lancer la suite de tests automatisés pour l'application.

Clé	Type	Oblig.	Description
`run_command`	`string`	Oui	La commande à exécuter pour lancer les tests (ex: `pytest`, `npm test`, `mvn test`).

Note : La commande est exécutée dans un conteneur test-runner dédié lors de apps test ou apps test-all.

Exemple Complet

app_name: crm-demo
version: '1.1'
infra_dependencies:
  - database
  - cache

components:
  - name: backend-api
    path: ./api
    type: python
    run_command: "gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000"
    public_port: 8000
    local_domain: "api.crm.127.0.0.1.nip.io"
    public_domain: "api.crm.nekristo.com"
    letsencrypt: true
    healthcheck:
      path: /health
      interval: 45s
      start_period: 20s
    database:
      name: "crm_main_db"
      migration_command: "alembic upgrade head"
    required_secrets:
      - JWT_SECRET_KEY
      - EXTERNAL_API_TOKEN
    development:
      run_command: "uvicorn main:app --host 0.0.0.0 --port 8000 --reload"
      volumes:
        - "./api:/app"
    deployment:
      image_name: "ghcr.io/my-org/crm-backend"
      strategy: blue-green
      hooks:
        pre_deploy: "alembic upgrade head"

  - name: frontend-app
    path: ./frontend
    dockerfile: Dockerfile.prod # Utilise un Dockerfile custom
    build_command: "npm run build" # Utilisé si Dockerfile.prod est un template .tpl
    public_port: 80
    local_domain: "crm.127.0.0.1.nip.io"
    public_domain: "crm.nekristo.com"
    letsencrypt: true
    required_secrets:
      - GTM_TRACKING_ID # Exemple de secret pour le frontend
    development:
      run_command: "npm run dev" # Lance le serveur de dev Vite/Next/etc.
      volumes:
        - "./frontend:/app"
        - "/app/node_modules" # Volume anonyme pour node_modules
    deployment:
      strategy: blue-green
      # Pas de hooks pour le frontend ici

tests:
  run_command: "pytest api/tests"

Référence du Manifeste nekristo.yml

Structure Globale

La Section components

Sous-section healthcheck

Sous-section database

Sous-section development

Sous-section deployment

Sous-section hooks (dans deployment)

La Section tests