Aller au contenu

Référence des Commandes CLI

Le nekristo-cli est l'outil principal pour interagir avec la plateforme.

Commandes Globales (Raccourcis)

nekristo-cli up

🚀 Démarre l'infrastructure partagée. Raccourci pour platform up.

nekristo-cli down

🛑 Arrête l'infrastructure partagée. Raccourci pour platform down.

nekristo-cli status

📊 Affiche le statut de tous les conteneurs. Raccourci pour platform status.

Commandes de la Plateforme (platform)

Gère l'infrastructure globale de la plateforme.

platform up [PROFILES...]

Démarre l'infrastructure partagée (Nginx Proxy Manager, services partagés comme Postgres, Redis, etc.).

Accepte des profils en argument (ex: nekristo-cli platform up database cache).

Si aucun profil n'est spécifié, tous les services définis dans shared-infra/docker-compose.yml (sans profil) et npm-stack/docker-compose.yml sont démarrés.

platform down

Arrête tous les conteneurs de l'infrastructure partagée (npm-stack et shared-infra).

platform status

Affiche le statut de tous les conteneurs Docker (infrastructure et applications locales) dans un tableau enrichi, incluant les URL locales si disponibles.

platform services

Liste tous les services partagés configurés dans platform.yml (section shared_infra_services), leur conteneur Docker et leur description.

platform open <service>

Ouvre l'interface web (si définie par une clé url dans platform.yml) d'un service partagé dans votre navigateur par défaut (ex: grafana, pgadmin, npm).

platform shell <service>

Ouvre un shell interactif dans le conteneur d'un service partagé (ex: platform shell postgres pour psql, platform shell redis pour redis-cli).

La commande exécutée est définie par shell_cmd dans platform.yml.

platform logs <service>

Affiche les logs Docker d'un conteneur de service partagé.

Options : - --follow (ou -f) pour suivre les logs - --tail <N> pour afficher les N dernières lignes

platform setup-proxy

Scanne les local_domain de tous les manifestes nekristo.yml dans apps/ et configure automatiquement Nginx Proxy Manager (démarré via platform up) pour router ces domaines vers les conteneurs de développement correspondants.

Lit les identifiants NPM depuis secrets.dev.yml ou les demande interactivement.

platform provision-vps --host <ip> [--repo-url <url>] [--initial-port <port>] [--root-user <user>] [--new-port <port>]

🚀 Provisionne et sécurise un VPS Ubuntu/Debian vierge pour le déploiement.

Se connecte en root (via initial-port, défaut 22), crée un nouvel utilisateur (new_user défini dans platform.yml, défaut nekristo), installe Docker, Python, UFW, Fail2ban, s3cmd, configure SSH sur un nouveau port (new_ssh_port), clone le dépôt (repo_url), installe la CLI sur le serveur, et génère une clé SSH pour les déploiements GitHub Actions.

Tente aussi de configurer automatiquement les secrets GitHub Actions via le CLI gh à la fin.

Les paramètres peuvent être fournis via options ou lus depuis la section provisioning de platform.yml.

Commandes Serveur (server)

Gère le VPS distant (production/staging) via SSH en utilisant les informations de platform.yml.

server connect

Ouvre un shell SSH interactif (bash) direct sur le VPS configuré dans platform.yml.

server update

Met à jour les paquets système (apt update && apt upgrade -y) sur le VPS (demande confirmation).

server usage

Affiche l'utilisation actuelle du disque (df -h) et de la RAM (free -h) du VPS.

server reboot

Redémarre le VPS (demande une double confirmation).

server docker-status

Affiche la liste des conteneurs Docker actifs (docker ps) sur le VPS.

server docker-prune

Nettoie les ressources Docker inutilisées (images, conteneurs, volumes, réseaux) sur le VPS (docker system prune -af, demande confirmation).

server docker-start <container_name>

Démarre un conteneur spécifique arrêté sur le VPS (docker start <container_name>).

server docker-stop <container_name>

Arrête un conteneur spécifique en cours d'exécution sur le VPS (docker stop <container_name>).

server docker-restart <container_name>

Redémarre un conteneur spécifique sur le VPS (docker restart <container_name>).

server ufw-status

Affiche l'état et les règles actuelles du pare-feu (sudo ufw status verbose) sur le VPS.

server ufw-allow <port>

Ajoute une règle pour AUTORISER le trafic entrant sur un port/service spécifié sur le VPS (sudo ufw allow <port>, demande confirmation).

Exemple : server ufw-allow 8080/tcp

server ufw-deny <port>

Ajoute une règle pour BLOQUER le trafic entrant sur un port/service spécifié sur le VPS (sudo ufw deny <port>, demande confirmation).

server fail2ban-status

Vérifie l'état de Fail2ban pour le service sshd et affiche les adresses IP actuellement bannies (sudo fail2ban-client status sshd).

server logs-system <service_name>

Affiche les 100 dernières lignes des logs système (via journalctl) pour un service systemd spécifique sur le VPS (ex: docker, sshd, nginx).

server setup-gpg

🔑 Exporte la clé GPG privée locale (basée sur le gpg_recipient de platform.yml) et l'importe sur le VPS.

Cette étape est requise pour permettre à la CI (ci deploy) de déchiffrer les fichiers secrets (secrets.prod.yml.gpg) sur le serveur.

server db-backup <app_name> [--download] [--upload | --no-upload] [--keep-local-on-server]

Crée une sauvegarde de la base de données PostgreSQL d'une application spécifique sur le VPS en exécutant apps db backup à distance.

Options : - --upload (défaut) / --no-upload : Tente d'uploader la sauvegarde vers l'Object Storage S3 configuré dans les secrets (nécessite s3cmd sur le VPS et les secrets S3_* dans .env distant) - --download (ou -d) : Télécharge le fichier .sql généré sur votre machine locale - --keep-local-on-server : Ne supprime pas le fichier .sql du VPS après un upload S3 réussi

server db-list-backups

Liste les fichiers de sauvegarde (*.sql) présents dans le répertoire du projet sur le VPS (ls -lh <remote_repo_path>/*.sql).

server db-restore <app_name> <local_backup_file>

⚠️ Opération destructive ! Restaure une base de données sur le VPS à partir d'un fichier de sauvegarde .sql situé sur votre machine locale.

Le fichier local est uploadé temporairement sur le VPS, puis la commande apps db restore est exécutée à distance avant de nettoyer le fichier temporaire (demande une double confirmation).

Gestion des Applications (apps)

Gère le cycle de vie des applications individuelles (développement local).

apps new <nom-app> [--template <nom-template>]

Crée une nouvelle structure de répertoire pour une application dans apps/.

Si --template <nom> est utilisé, copie le contenu du template correspondant depuis nekristo_cli/skeletons/apps/<nom> et traite les fichiers *.tpl (remplace {{APP_NAME}}).

Si aucun template n'est fourni ou choisi interactivement, crée un répertoire vide.

apps init

Lance un assistant interactif pour générer le fichier manifeste nekristo.yml pour une application existante.

Note : Doit être lancé depuis le répertoire d'une application (ex: apps/mon-app/)

apps gen-docker [--app-name <nom-app>] [--env <env>]

(Re)génère les fichiers Dockerfile (si non personnalisés) et docker-compose.<env>.yml (ou docker-compose.yml pour dev) à partir du manifeste nekristo.yml.

Détecte <nom-app> si lancé depuis le dossier de l'app. L'environnement par défaut est dev.

apps start [nom-app]

▶️ Démarre une application (et ses dépendances d'infrastructure ou d'autres apps listées dans infra_dependencies/app_dependencies) en mode développement local.

Crée automatiquement la base de données (via ensure_database_exists) si déclarée dans le manifeste.

Utilise les paramètres de la section development du manifeste s'ils existent (pour run_command de dev, volumes pour hot-reloading).

Exécute docker compose up -d --build. Détecte nom-app si omis.

  • --no-detach : Affiche les logs en direct dans le terminal (ne détache pas les conteneurs). Très utile pour déboguer les erreurs au démarrage.
  • --no-cache : Force la reconstruction de toutes les images Docker sans utiliser le cache.

apps stop [nom-app] [--with-volumes]

⏹️ Arrête les conteneurs d'une application (docker compose down).

Si --with-volumes (ou --clean) est utilisé, supprime aussi les volumes Docker associés (docker compose down -v). Détecte nom-app si omis.

apps restart <nom-app>

🔄 Redémarre une application (équivalent à apps stop suivi de apps start).

apps run <nom-app> <nom-composant> <commande...>

🏃 Exécute une commande unique dans un nouveau conteneur (one-shot) pour un composant spécifique de l'application (docker compose run --rm <composant> <commande...>).

Utile pour lancer des tâches ponctuelles comme des scripts.

apps shell <nom-app> <nom-composant>

🐚 Ouvre un shell interactif (bash ou sh) à l'intérieur d'un conteneur en cours d'exécution d'un composant (docker exec -it <container_name> bash/sh).

apps logs [nom-app] [-f] [--tail <N>]

📜 Affiche les logs agrégés de tous les conteneurs d'une application (docker compose logs).

Options : - --follow (ou -f) pour suivre les logs - --tail <N> pour afficher les N dernières lignes

Détecte nom-app si omis.

Note : Les logs sont aussi centralisés dans Loki/Grafana si configuré.

apps validate [nom-app]

✅ Valide la syntaxe et la logique de base du manifeste nekristo.yml d'une application.

Détecte nom-app si omis.

apps validate-all

✅ Valide les manifestes nekristo.yml de toutes les applications trouvées dans apps/.

apps config-view [nom-app]

👀 Affiche le contenu du manifeste nekristo.yml d'une application, tel qu'il est interprété par la CLI (après chargement YAML).

Détecte nom-app si omis.

apps test [nom-app]

🔬 Lance la suite de tests pour une application, telle que définie par tests.run_command dans son manifeste nekristo.yml.

Démarre un conteneur test-runner dédié pour exécuter la commande. Détecte nom-app si omis.

apps test-all

🧪 Lance les suites de tests pour toutes les applications du projet ayant une section tests définie dans leur manifeste.

apps bootstrap <nom-app> [--template <nom-template>]

🚀 Raccourci pour créer et configurer une nouvelle application : équivalent à apps new → apps gen-docker → platform setup-proxy.

apps setup <nom-app>

🔧 Raccourci pour (re)configurer une application existante (utile après git pull ou modification manuelle) : équivalent à apps gen-docker → platform setup-proxy.

Sous-commandes apps db

Gère les bases de données des applications en environnement local (dev).

apps db migrate [nom-app]

🧬 Exécute la commande de migration de base de données (définie dans database.migration_command du manifeste) dans un conteneur one-shot pour l'application spécifiée.

Détecte nom-app si omis.

apps db seed [nom-app]

🌱 Exécute la commande de "seeding" (définie dans database.seeding_command du manifeste) dans un conteneur one-shot pour peupler la base de données de l'application.

Détecte nom-app si omis.

apps db backup <nom-app> [-o <fichier>]

💾 Crée une sauvegarde (pg_dump) de la base de données locale (dev) d'une application dans un fichier .sql (nom généré par défaut ou spécifié via -o).

apps db restore <app_name> <fichier_backup>

🔄 ⚠️ Opération destructive ! Restaure une base de données locale (dev) à partir d'un fichier de sauvegarde .sql spécifié (demande confirmation).

Gestion des Secrets (secrets)

Gère les fichiers secrets.<env>.yml (clair pour dev) et secrets.<env>.yml.gpg (chiffrés pour les autres environnements).

secrets edit [--env <env>]

Édite le fichier de secrets pour un environnement donné.

Comportement : - Si --env est omis, édite secrets.dev.yml - Si --env est présent sans valeur (ex: secrets edit --env), propose une liste interactive (dev, staging, production, etc.) - Pour dev, ouvre secrets.dev.yml directement. Vérifie d'abord les required_secrets dans les manifestes et ajoute les clés manquantes avec "TODO" avant d'ouvrir l'éditeur. - Pour les autres environnements (ex: prod), demande la passphrase GPG, déchiffre secrets.<env>.yml.gpg dans un fichier temporaire, vérifie/ajoute les required_secrets manquants, ouvre ce fichier temporaire dans l'éditeur, puis rechiffre le résultat dans le fichier .gpg original

secrets view --env <env>

Affiche le contenu d'un fichier de secrets dans le terminal.

Défaut : --env dev

Pour les environnements chiffrés, demande la passphrase GPG pour déchiffrer avant d'afficher.

secrets apply --env <env> [--force]

Génère les fichiers .env dans chaque répertoire d'application (apps/<app_name>/.env) et pour l'infrastructure partagée (shared-infra/<version>/.env) à partir du fichier de secrets secrets.<env>.yml ou secrets.<env>.yml.gpg correspondant.

Défaut : --env dev

Pour les environnements chiffrés (prod, staging...), l'opération est bloquée par défaut en dehors d'un environnement CI (détecté via CI=true).

Utilisez --force pour outrepasser cette sécurité (demande la passphrase GPG si non fournie via GPG_PASSPHRASE).

Intégration Continue (ci)

Commandes principalement utilisées par le workflow GitHub Actions.

ci gen-workflow [--dry-run] [--all] [--include-scan]

Génère ou met à jour le fichier de workflow GitHub Actions (.github/workflows/deploy.yml).

Par défaut, le workflow détecte les changements pour ne builder/déployer que les applications modifiées.

Options : - --all : Force le workflow à builder et déployer toutes les applications, en ignorant la détection des changements - --include-scan : Ajoute les étapes de scan de vulnérabilités (Trivy) aux jobs de build

ci deploy --environment <env> [--tag <tag>] [--app <app>...] [--dry-run]

Commande principale utilisée par le workflow pour déployer un environnement spécifique sur le serveur correspondant.

Processus : - Déchiffre le fichier secrets.<env>.yml.gpg en utilisant GPG_PASSPHRASE (fournie par les secrets GitHub Actions) - Applique les secrets pour générer les fichiers .env sur le serveur - Crée automatiquement la base de données pour l'environnement cible si elle est déclarée dans le manifeste et n'existe pas - Génère le fichier docker-compose.<env>.yml - Lance les déploiements : - Utilise la stratégie Blue-Green (via BlueGreenDeployer) si configurée dans le manifeste et si un public_domain est défini. Interagit avec Nginx Proxy Manager (via NpmClient) en utilisant les secrets NPM_* fournis par GitHub Actions - Utilise une mise à jour standard (rolling update via docker compose up -d) sinon

Options : - --tag : Spécifie le tag Docker à utiliser (généralement le SHA du commit) - --app : Permet de cibler des applications spécifiques (sinon, toutes sont déployées) - --dry-run : Simule les étapes sans exécuter les commandes docker compose ou modifier NPM

ci setup-proxies --url <npm_url> --email <npm_email> --password <npm_pass>

Utilisé par le workflow après ci deploy.

Scanne tous les manifestes, détermine les public_domain effectifs pour chaque environnement, et configure (crée ou met à jour) les hôtes proxy correspondants dans Nginx Proxy Manager en utilisant les identifiants fournis (qui proviennent des secrets GitHub Actions NPM_*).

Configure aussi Let's Encrypt si letsencrypt: true est défini dans le manifeste.

ci setup-secrets [--host <ip>] [--user <user>] [--port <port>] [--key <ssh_key>] [--skip-check]

🔒 Configure automatiquement les secrets requis (SSH_HOST, SSH_USERNAME, SSH_PORT, SSH_PRIVATE_KEY, GPG_PASSPHRASE, NPM_URL, NPM_EMAIL, NPM_PASSWORD) dans les "Secrets GitHub Actions" de votre dépôt en utilisant le CLI gh installé localement.

Demande interactivement les informations non fournies via les options. Simplifie grandement la configuration post-provisionnement du VPS.