Foire Aux Questions (FAQ)

Cette section répond aux questions courantes concernant l'utilisation de la plateforme Nekristo et de nekristo-cli.

Configuration & Développement

Q : Comment configurer des variables d'environnement pour mon application ou un composant spécifique ?

R : Il y a trois façons principales :

1. Secrets (Recommandé pour clés API, mots de passe...)

Utilisez nekristo-cli secrets edit --env <environnement> pour ajouter/modifier vos variables.

Les variables sont stockées sous la clé apps: <nom-de-votre-app>: dans secrets.<env>.yml(.gpg).

# secrets.dev.yml (ou secrets.prod.yml.gpg)
apps:
  mon-app:
    API_KEY: "valeur_dev"
    DATABASE_URL: "sera_surcharge_par_cli" # Injecté automatiquement si 'database' est défini
  autre-app:
    STRIPE_KEY: "pk_test_..."

Lancez nekristo-cli secrets apply --env <environnement> pour générer les fichiers .env correspondants dans apps/<app_name>/.env. Ces variables sont chargées par Docker Compose.

2. Manifeste `nekristo.yml` - Section `environment` (Pour variables NON sensibles PUBLIQUES)

Vous pouvez définir des variables directement dans la section components sous la clé environment.

# apps/mon-app/nekristo.yml
components:
  - name: web
    # ... autres clés ...
    environment:
      NODE_ENV: production
      LOG_LEVEL: info

Ces variables sont utiles pour la configuration non secrète (ex: mode de fonctionnement).

⚠️ Elles sont visibles dans le code source versionné. Ne les utilisez PAS pour des informations sensibles.

3. Manifeste `nekristo.yml` - Section `required_secrets` (Pour DÉCLARER les secrets nécessaires)

Ajoutez une liste required_secrets à votre composant pour indiquer les noms des variables d'environnement sensibles qu'il attend.

# apps/mon-app/nekristo.yml
components:
  - name: backend
    # ... autres clés ...
    required_secrets:
      - STRIPE_SECRET_KEY
      - SENDGRID_API_KEY

Lorsque vous lancez nekristo-cli secrets edit, la commande vérifiera si ces clés existent dans le fichier secrets.*.yml(.gpg) sous apps: mon-app:.

Si une clé manque, elle sera automatiquement ajoutée avec la valeur "TODO: Add value", vous invitant à la remplir.

Cela aide à ne pas oublier de configurer les secrets nécessaires.

Q : Comment activer le hot-reloading (rechargement automatique) pour mon service backend en développement ?

R : Ajoutez une section development à votre composant dans nekristo.yml.

Spécifiez une run_command qui utilise l'option de rechargement de votre framework (ex: --reload pour Uvicorn/FastAPI) et montez le code source via volumes.

# apps/mon-app/nekristo.yml
components:
  - name: backend
    path: ./backend
    type: python
    run_command: "uvicorn main:app --host 0.0.0.0 --port 8000" # Prod
    development:
      run_command: "uvicorn main:app --host 0.0.0.0 --port 8000 --reload" # Dev
      volumes:
        - "./backend:/app" # Monte le code
    # ...

Q : Ma base de données n'est pas créée automatiquement ?

R : Assurez-vous que :

database est listé dans infra_dependencies de votre nekristo.yml
Au moins un composant a une section database: { name: "mon_nom_de_db" }
Vous lancez nekristo-cli apps start mon-app (pour dev) ou que le déploiement CI (nekristo-cli ci deploy --environment <env>) s'exécute

Ces commandes déclenchent la création de la BDD via ensure_database_exists si elle n'existe pas.

Le nom de la BDD en production/staging sera suffixé par l'environnement (ex: mon_nom_de_db_staging).

Déploiement & CI/CD

Q : Pourquoi mon pipeline échoue à l'étape "Scan Image" ?

R : Le scan Trivy (configuré dans .github/workflows/deploy.yml) échoue intentionnellement s'il détecte des vulnérabilités CRITICAL ou HIGH.

Mettez à jour les dépendances (OS, librairies) dans votre Dockerfile ou requirements.txt / package.json. Testez localement avec trivy image <votre-image>.

Q : Comment forcer un redéploiement même si mon code n'a pas changé ?

R : Le workflow GitHub Actions est déclenché par un push sur la branche de déploiement.

Pour forcer un redéploiement :

Option 1 : Empty commit

git checkout <branche-deploy>
git commit --allow-empty -m "chore: Force redeploy"
git push origin <branche-deploy>

Option 2 : Relancer manuellement

Utilisez l'interface GitHub Actions pour relancer manuellement un workflow ("Re-run jobs").

Q : La commande `ci setup-secrets` ne fonctionne pas.

R : Vérifiez que :

Vous avez installé le CLI GitHub (gh)
Vous êtes authentifié (gh auth status puis gh auth login si besoin)
Vous avez les permissions d'écriture sur les secrets du dépôt GitHub

Sauvegardes & Object Storage

Q : Comment sont gérées les sauvegardes de base de données en production ?

R : La commande nekristo-cli server db-backup <app_name> permet de créer une sauvegarde de la base de données d'une application directement sur le VPS.

Fonctionnement :

Par défaut (--upload), elle tente ensuite d'uploader cette sauvegarde vers l'Object Storage S3 configuré dans vos secrets (via s3cmd sur le VPS). Les secrets S3_* doivent être définis dans secrets.<env>.yml.gpg et appliqués sur le serveur
Vous pouvez télécharger la sauvegarde sur votre machine locale avec l'option --download
Vous pouvez lister les sauvegardes sur le VPS avec server db-list-backups
La restauration se fait via server db-restore <app_name> <fichier_local.sql>, qui uploade votre fichier local sur le VPS avant de restaurer

Sécurité

Q : Où sont stockés les secrets de production sur le VPS ?

R : Les fichiers secrets.prod.yml.gpg, secrets.staging.yml.gpg, etc., sont clonés avec le code dans /home/<user>/<repo_name>.

Ils restent chiffrés sur le disque.

La commande nekristo-cli ci deploy (exécutée par la CI) les déchiffre en mémoire en utilisant la GPG_PASSPHRASE fournie par les secrets GitHub Actions pour générer les fichiers .env.

Les fichiers .env sur le serveur contiennent les secrets en clair, mais l'accès au serveur est sécurisé (SSH par clé, UFW, Fail2ban).