Avancé

cipi api

Cipi peut éventuellement activer une couche REST API sur le serveur via cipi api <domain>. Il est alimenté par le package Laravel cipi/api (version actuelle 1.20), qui expose :

• REPOS API — applications (y compris Octane create, .env, auth.json, Artisan, sur liste blanche app run, déployer-config), alias, www redirections, déploiement, SSL, bases de données multimoteurs, journaux d'applications, état du serveur (/api/*)
• Serveur MCP — Plus de 50 outils sur /mcp(Diffusion HTTP)
• Poste de pilotage du serveur — PHP installation/commutation, clés SSH, services, SMTP, contrôles de santé, Liste blanche IP (API 1.15.0+ / Cipi 5.0.6+)
• Interface utilisateur Swagger — référence interactive sur /docs

Nécessite PHP 8.2+ et Laravel 12+ sur l'hôte du panneau. C'est au niveau du serveur automatisation - distincte de l'application par application CipiAgent paquet (cipi/agent sur chaque application Laravel).

Le cipi/api paquet

Sur un serveur Cipi normal, vous n'installez jamais le package manuellement — cipi api <domain> dispositions HTTP à /opt/cipi/api, Nginx, SSL, file d'attente des tâches SQLite et cipi-queue.service. Pour référence ou configurations personnalisées :

$ composer require cipi/api
$ php artisan vendor:publish --tag=cipi-config
$ php artisan vendor:publish --tag=cipi-assets
$ php artisan migrate
$ php artisan cipi:seed-api-user
$ php artisan cipi:token-create

Panneau .env utilise CIPI_APPS_JSON=/etc/cipi/apps.json (ou apps-public.jsonprojection pour les champs non sensibles). Les capacités des jetons sont définies dans config/cipi.php — liste-les avec php artisan cipi:token-abilities (même liste comme cipi api token create depuis Cipi 4.6.3).

Source et journal des modifications : github.com/cipi-sh/api (MIT). Emballage client : cipi-cli.

Commandes

$ cipi api <domain>           # configure API at root (e.g. api.myhosting.com)
$ cipi api ssl                  # install Let's Encrypt certificate for API domain
$ cipi api token list           # list tokens
$ cipi api token create         # create a new token (choose abilities)
$ cipi api token revoke <id>    # revoke a token
$ cipi api status               # Laravel + cipi-api versions, queue worker, pending jobs, FPM pool
$ cipi api fix-permissions      # repair panel storage/database ownership (www-data)
$ cipi api update               # soft update: composer update on Laravel and API packages
$ cipi api upgrade              # full rebuild with rollback at /opt/cipi/api.old

Dépannage du panneau API

Après cipi self-update, fichiers appartenant à la racine sous /opt/cipi/api ou /opt/cipi/gui peut empêcher PHP-FPM (www-data) à partir de l'écriture de journaux ou du Base de données de tâches SQLite : le navigateur affiche un simple HTTP 500 sur /docs ou /mcp. Cipi répare normalement automatiquement la propriété lors de la mise à jour automatique (migration 5.0.13+ récupère la propriété API/GUI ); si les problèmes persistent :

$ cipi api fix-permissions   # chown storage, database, bootstrap/cache, .env → www-data
$ cipi api status              # confirm Laravel version, queue worker, pending jobs

cipi api status imprime le Laravel installé et cipi/api versions de paquets, que ce soit cipi-queue.service est actif, en attente de travaux asynchrones dans la base de données SQLite du panel, et les statistiques du pool PHP-FPM pour le vhost API (y compris les requêtes lentes une fois configurées). cipi api update met à jour en douceur le package du panneau API de Packagist (depuis 5.0.15; la migration supprime les entrées de dépôt VCS obsolètes). cipi api upgrade effectue une reconstruction complète avec restauration à /opt/cipi/api.old. Depuis 5.0.14–5.0.17, la mise à jour automatique utilise des archives tar GitHub chronométrées et la distribution Packagist s'installe au lieu de bloquer les clones VCS Composer pour les packages API et GUI. Depuis 5.0.18, GUI mise à niveau/mise à jour évite les liens symboliques Composer qui cassent PHP-FPM open_basedir (HTTP 500 ); courir cipi gui fix-permissions ou cipi self-update pour réparer les panneaux existants.

Depuis v4.7.18 (migrations 4.7.15–4.7.18), Pannes du panneau API sur Ubuntu 25.10+ / 26.04 sont fixés de bout en bout : sudo-rs rejets cipi db restore * * caractères génériques (tout le fichier sudoers a été ignoré — J'ai peur de ne pas pouvoir faire ça), donc la liste blanche utilise des éléments de fin * seulement; approvisionnement common.sh n'abandonne plus les commandes en lecture seule lorsque /etc/cipi est remonté en lecture seule ; HTTP open_basedir comprend /usr/local/bin/ pour les aides-journaux ; et cipi db list affiche les bases de données vides et fait apparaître des erreurs dans le coffre-fort/MariaDB. Courir cipi self-update postuler.

Création de jetons et autorisations granulaires

Utilisations de l'authentification Sanctuaire. Chaque jeton peut avoir un ou plusieurs capacités que limiter les opérations autorisées :

• apps-view - lire des applications
• apps-create — créer des applications
• apps-edit — modifier les applications (PHP, référentiel, branche, domaine principal depuis API 1.9.0+ / Cipi 4.6.2+)
• apps-suspend - suspendre et réactiver les applications
• apps-basicauth - activer, désactiver et inspecter HTTP Basic Auth sur les applications (API 1.10.0+)
• apps-env — lister/fusionner l'application .env clés (API 1.14.0+ / Cipi 5.0.3+)
• apps-auth — gérer les Composer partagés auth.json (HTTP 1.14.0+; distinct de apps-basicauth)
• apps-artisan — exécutez Artisan en tant que tâche asynchrone (API 1.14.0+)
• apps-run — non interactif sur liste blanche app run (API 1.14.0+)
• apps-deploy-config — options de recettes structurées du déployeur (API 1.14.0+)
• php-view — liste des versions PHP installées (API 1.15.0+)
• php-manage — installer/supprimer PHP, définir la valeur par défaut du système (API 1.15.0+ / 1.17.0+ pour PUT /api/php/default)
• ssh-view — lister les clés SSH sur le cipi utilisateur (API1.15.0+)
• ssh-manage — ajouter/supprimer/renommer des clés SSH (API 1.15.0+)
• services-view — liste des services système (API 1.15.0+)
• services-manage — redémarrer les services (API 1.15.0+)
• smtp-view — lire les paramètres de notification SMTP (le mot de passe n'a jamais été renvoyé ; API 1.15.0+)
• smtp-manage — configurer, activer, désactiver, tester, supprimer SMTP (API 1.15.0+)
• health-view — liste des contrôles de santé (API 1.15.0+)
• health-manage - définir, désactiver et exécuter des contrôles de santé par application (API 1.15.0+)
• ip-whitelist-view — lire le panneau API / MCP Liste autorisée IP (API 1.15.0+)
• ip-whitelist-manage — modifier les entrées de la liste d'autorisation IP (API 1.15.0+)
• apps-delete — supprimer des applications
• deploy-manage - déployer, restaurer, déverrouiller
• ssl-manage — installer et gérer les certificats SSL
• aliases-view — lire les pseudonymes
• aliases-create — ajouter des alias
• aliases-delete — supprimer les alias
• www-manage — Contrepartie www/apex et redirections (API 1.12.0+ / Cipi 4.8+)
• dbs-view — lister les bases de données
• dbs-create — créer des bases de données
• dbs-delete — supprimer des bases de données
• dbs-manage — sauvegarde, restauration, régénération du mot de passe
• status-view — lire l'instantané de l'état du serveur (GET /api/status, API 1.11.6+)
• mcp-access — accéder au serveur MCP

Depuis Cipi 4.6.3 / API 1.11.7+, cipi api token create lit la liste des capacités canoniques du package panel API (mêmes entrées que php artisan cipi:token-abilities sur le serveur). Migrations 4.6.3modernise les serveurs existants avec la liste mise à jour (y compris status-view, apps-suspend, et apps-basicauth).

Points de terminaison REST

Tous les points de terminaison nécessitent le Authorization: Bearer <token> en-tête. Opérations d'écriture (créer, modifier, supprimer, déployer, restaurer, déverrouiller, SSL, alias, www, base de données) sont asynchrones : ils retour 202 Accepted avec un job_id interroger via GET /api/jobs/{id}. Points de terminaison en lecture seule tels que GET /api/dbs, GET /api/dbs/engines, GET /api/status, GET /api/apps/{name}/www, et GET /api/apps/{name}/logs (HTTP 1.11.9+), GET /api/php, GET /api/ssh/keys, GET /api/services, GET /api/smtp, GET /api/health, GET /api/ip-whitelist (HTTP 1.15.0+ / Cipi 5.0.6+) sont synchrones. POST /api/apps accepte en option custom (booléen) et docroot (chaîne) paramètres pour la création applications personnalisées avec un déploiement classique. Le repository le champ est requis pour Laravel applications et facultatif pour les applications personnalisées : omettez-le (ou envoyez-le vide) pour provisionner un site SFTP uniquement aligné avec Cipi v4.5.1+. Lorsqu'aucun référentiel n'est défini, branch est omis. Depuis API 1.12.0+ / Cipi 4.8+, Laravel création d'application accepte également facultatif engine (mariadb ou pgsql) pour choisir la base de données moteur. Depuis API 1.13.0+ / Cipi 5.0+, Laravel création d'application accepte facultatif octane (true ou "frankenphp") pour fournir Laravel Octane (FrankenPHP); octane est rejeté lorsque custom est réglé. L'outil MCP AppCreate suit les mêmes règles. Gardez le API paquet actuel avec cipi api update / cipi api upgrade donc validation et OpenAPI correspond à ce comportement.

POST /api/apps/{name}/suspend met une application hors ligne en échangeant son hôte virtuel Nginx contre un générique HTTP 503 page de maintenance (HTTPS inclus) sans la supprimer, tout en POST /api/apps/{name}/unsuspend restaure le vhost normal. Les deux nécessitent le apps-suspend capacité et retour 409 si l'application est déjà dans la cible état. Le suspended le drapeau survit à la régénération du vhost et est exposé sur GET /api/apps et GET /api/apps/{name}. Ces points de terminaison nécessitent le API paquet 1.8.1+ et HTTP 4.5.8+ sur le serveur.

PUT /api/apps/{name} accepte une option domainchamp pour renommer le domaine principal de l’application. Depuis API 1.15.0+ / Cipi 5.0.6+, le le point de terminaison transmet uniquement les champs qui diffèrent de l'application actuelle (empêche l'absence d'opération webhook ou la clé de déploiement loisirs lorsque PHP ou la branche sont inchangés). PHP doit être installé sur l'hôte (422 sinon). Le API valide le format de manière synchrone et renvoie 409si le domaine est déjà utilisé par une autre application (les alias de l'application actuelle sont autorisé, favorisant ainsi un alias pour les œuvres principales). Nécessite le package API 1.9.0+ et HTTP 4.6.2+. L'outil MCP AppEdit accepte la même chose domain paramètre.

GET /api/apps et GET /api/apps/{name} exposer un booléen suspended et basic_auth drapeaux par application (à partir de apps.json). Depuis API 1.12.0+ ils exposent également engine, www_redirect, et force_https de apps-public.json / apps metadata. Since API 1.13.0+ ils exposent octane et octane_port pour Octane applications.

HTTP Points de terminaison d'authentification de base sous /api/apps/{name}/basicauth/* envelopper cipi basicauth de manière synchrone - ils ne renvoient pas de job_id. Activer les acceptations facultatif user et password (généré automatiquement en cas d'omission ; renvoyé une fois dans la réponse). Nécessite le apps-basicauth capacité et package API 1.10.0+. Ceci est distinct de Composer auth.json gestion - voir cipi basicauth.

Points de terminaison WWW/apex sous /api/apps/{name}/www/* envelopper cipi www (HTTP 1.12.0+ / Cipi 4.8+). GET …/www est synchrone et renvoie primary, apex, www, et redirect. POST …/www/add, …/force-to-root, …/force-from-root, et …/clear sont des travaux asynchrones. Nécessite le www-manage capacité. MCP outils : WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear.

POST /api/apps/{name}/ssl/force réapplique la redirection HTTP → HTTPS sans émettre de message nouveau certificat (cipi ssl force). Nécessite ssl-manage et HTTP 1.12.0+. Outil MCP : SslForce.

GET /api/dbs répertorie les bases de données de manière synchrone en exécutant sudo cipi db list sur l'hôte (identique au serveur CLI). Requête facultative engine=mariadb|pgsql filtres par moteur (API 1.12.0+ / Cipi 4.8+). GET /api/dbs/engines répertorie les moteurs installés et le serveur par défaut (synchronisation ; MCP DbEngines). Autre /api/dbs/* opérations d'écriture sont des tâches asynchrones et acceptent des tâches facultatives engine lors de la création, de la suppression, de la sauvegarde, de la restauration, et mot de passe. Les commandes de base de données nécessitent Cipi 4.4.17+ sur le serveur (cipi db … entrées dans la liste blanche des sudoers API ); besoins de support multimoteur Cipi 4.8+.

POST /api/apps/{name}/webhook/recreate recrée le déploiement GitHub/GitLab webhook ; corps en option { "rotate_secret": true } tourne également CIPI_WEBHOOK_TOKEN dans apps.json et shared/.env. Tâche asynchrone (app-webhook-recreate; capacité apps-edit; HTTP cipi app webhook recreate [--rotate-secret]; HTTP 1.15.0+ / Cipi 5.0.6+). MCP : AppWebhookRecreate.

Gestion de PHP (HTTP 1.15.0+ / Cipi 5.0.6+): GET /api/php répertorie les versions installées (synchronisation ; capacité php-view). POST /api/php/install et DELETE /api/php/{version} installer ou supprimer un version (asynchrone ; php-manage). Depuis API 1.17.0+, PUT /api/php/default définit la valeur par défaut du système PHP de manière synchrone (corps { "version": "8.5" }; enveloppements cipi php switch; retours mis à jour GET /api/php charge utile). Les versions installables sont 8.3, 8.4, 8.5. MCP : PhpList.

Moteurs de base de données — POST /api/dbs/engines/install et PUT /api/dbs/engines/default (capacité dbs-manage; API 1.15.0+).

Clés SSH — GET|POST /api/ssh/keys, DELETE /api/ssh/keys/{n} (capacités ssh-view / ssh-manage; API 1.15.0+).

Prestations — GET /api/services, POST /api/services/{name}/restart (capacités services-view / services-manage; API 1.15.0+).

SMTP — GET|PUT|DELETE /api/smtp, POST /api/smtp/enable|disable|test (capacités smtp-view / smtp-manage; le mot de passe n'a jamais été renvoyé sur GET ; HTTP 1.15.0+ / Cipi 5.0.6+ non interactif cipi smtp configure --host=…).

Bilans de santé — GET /api/health, GET|PUT|DELETE /api/apps/{name}/health, POST /api/apps/{name}/health/check (capacités health-view / health-manage; API 1.15.0+).

Liste blanche IP — middleware cipi.ip sur api/* et /mcp lit /etc/cipi/api-ip-whitelist (fichier manquant ou * = permettre tout). Les clients rejetés obtiennent 403 { "error": "IP not allowed", "ip": "…" }. REPOS : GET /api/ip-whitelist, PUT /api/ip-whitelist (entries, facultatif ensure_client_ip), POST /api/ip-whitelist (ip), DELETE /api/ip-whitelist (ip), POST /api/ip-whitelist/allow-all (capacités ip-whitelist-view / ip-whitelist-manage; HTTP cipi api ip-whitelist; HTTP 1.15.0+ / Cipi 5.0.6+). MCP : IpWhitelistShow.

GET /api/status renvoie le même JSON structuré que cipi status (système, ressources, services, pools PHP, nombre d'applications). Depuis API 1.11.8+ le point final préfère sudo cipi status sur l'hôte et revient aux lectures directes de l'hôte lorsque sudo est indisponible. Depuis API 1.12.1+ la solution de secours de lecture par l'hôte inclut postgresql lorsque l'unité systemd est installée (correspondant à Cipi 4.8+). Nécessite le status-view capacité (API 1.11.6+). Le MCP outil ServerStatus renvoie la même charge utile et ne nécessite que mcp-access. Depuis votre ordinateur portable, utilisez cipi-cli status pour un aperçu global de tous profils de serveur configurés ou détails d'un profil.

GET /api/apps/{name}/logs renvoie des instantanés de journaux paginés et synchrones pour nginx, PHP-FPM, Laravel (le cas échéant), les journaux de travail et de déploiement - l'équivalent REST de cipi app logs et cipi-cli apps logs. Paramètres de requête : type (par défaut all), page (par défaut 1, la plupart récente première), per_page (par défaut 50, maximum 1000). Nécessite le apps-view capacité et package API 1.11.9+. Le texte du journal est rédigé pour secrets communs (même politique que MCP AppLogs depuis API 1.11.5+).

Exemples REST (curl)

Définissez votre URL de base et votre jeton API (à partir de cipi api token create):

exporter CIPI_API_URL="https://api.myserver.com"
exporter CIPI_API_TOKEN="votre-jeton-de-sanctuaire"

Liste des applications (synchronisation, 200):

curl -sS "${CIPI_API_URL}/api/apps" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Accepter : application/json"

Statut du serveur (synchronisation, nécessite status-view):

curl -sS "${CIPI_API_URL}/api/statut" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}"

Journaux d'applications (synchronisation, nécessite apps-view, API 1.11.9+):

curl -sS "${CIPI_API_URL}/api/apps/myapp/logs?type=deploy&page=1&per_page=50" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Accepter : application/json"

Créer une application Laravel Octane (asynchrone, API 1.13.0+ / Cipi 5.0+; nécessite apps-create):

curl -sS -X POST "${CIPI_API_URL}/api/apps" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Accepter : application/json" \
  -H "Type de contenu : application/json" \
  -d '{
    "domaine": "boutique.exemple.com",
    "dépôt": "git@github.com:you/shop.git",
    "branche": "principale",
    "octane" : vrai,
    "moteur": "mariadb"
  }'

Envoyer "octane": "frankenphp" pour le même effet. Omettre octane pour le classique HTTP-FPM. Utiliser "engine": "pgsql" lorsque PostgreSQL est installé (API 1.12.0+ / Cipi 4.8+).

Application .env (synchronisation, API 1.14.0+ / Cipi 5.0.3+; nécessite apps-env):

curl -sS "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}"

curl -sS -X PUT "${CIPI_API_URL}/api/apps/myapp/env" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Type de contenu : application/json" \
  -d '{"set":{"APP_DEBUG":"false"},"unset":["LEGACY_KEY"]}'

Artisan / exécution de l'application (tâches asynchrones, API 1.14.0+; capacités apps-artisan / apps-run):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/artisan" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Type de contenu : application/json" \
  -d '{"command":"cache:clear"}'

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/run" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Type de contenu : application/json" \
  -d '{"command":composer install --no-dev"}'

curl -sS "${CIPI_API_URL}/api/run-commands" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}"

Sondage GET /api/jobs/{id} pour output / exit_code. Types d'emplois : app-artisan, app-run.

Déployer une application (asynchrone, 202 + job_id):

curl -sS -X POST "${CIPI_API_URL}/api/apps/myapp/deploy" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Accepter : application/json"

# poll until completed
curl -sS "${CIPI_API_URL}/api/jobs/JOB_ID" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}"

Sauvegarde de la base de données (asynchrone, dbs-manage) — renvoie un chemin de sauvegarde réel dans le travail result, pas un dump anonymisé (voir Anonymiseur d'agent):

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}"

Intégration hôte (sudoers)

Le panneau API fonctionne comme www-data et exécute les commandes Cipi CLI via sudo en utilisant /etc/sudoers.d/cipi-api — une liste blanche explicite de cipi sous-commandes. Les identifiants Vault et MariaDB restent dans Cipi, pas dans PHP.

• GET /api/dbs - court sudo cipi db list (synchronisation). Nécessite Cipi 4.4.17+ (la migration ajoute cipi db … aux sudoers). Sans cela : sudo: a terminal is required. Liste multi-moteurs/moteurs nécessaires Cipi 4.8+ / API 1.12.0+.
• GET /api/status / MCP ServerStatus - préférer sudo cipi status (HTTP 1.11.8+); secours de lecture par l'hôte en cas d'échec de sudo (comprend postgresql depuis API 1.12.1+).
• MCP ServiceList — sudo cipi service list
• MCP AppArtisan — sudo cipi app artisan <app> …
• Depuis Cipi 5.0.6+ / API 1.15+: php list|install|remove|switch, ssh list|add|remove, service list|restart, status, db install|default|engines, app webhook recreate, smtp status|configure|enable|disable|test|delete, api ip-whitelist (+ args) dans la liste blanche des sudoers (migration 5.0.6 crée le fichier de liste blanche IP par défaut et régénère /etc/sudoers.d/cipi-api sur cipi self-update).
• Depuis Cipi 5.0.3+ / API 1.14+: app env, app artisan, app run, auth create|edit|show|delete, et déployer-config dans la liste blanche des sudoers (la migration régénère /etc/sudoers.d/cipi-api sur cipi self-update).
• Travaux asynchrones — cipi app (y compris --octane / --engine), deploy, alias, www, ssl / ssl force, db create|delete|backup|restore|password|engines, etc

Après cipi self-update, cours cipi api fix-permissions si /docs ou /mcp retournez HTTP 500 (voir dépannage ci-dessus).

Liste blanche IP (CLI)

Depuis Cipi 5.0.6+, restreignez les clients du panneau API et MCP par adresse IP source. Fichier par défaut /etc/cipi/api-ip-whitelist est * (permettre tout). Une adresse IPv4/IPv6 ou CIDR par ligne (ou séparés par des virgules) --ips=).

$ cipi api ip-whitelist show
$ cipi api ip-whitelist add 203.0.113.10
$ cipi api ip-whitelist set --ips=203.0.113.0/24,2001:db8::/32
$ cipi api ip-whitelist allow-all
$ cipi api ip-whitelist show --json

Les équivalents REST vivent sous /api/ip-whitelist (HTTP 1.15.0+). PUT ajoute automatiquement l'adresse IP de l'appelant lors du resserrement de la liste, à moins que ensure_client_ip: false.

Swagger/OpenAPI

Une documentation interactive est disponible sur /docs (interface utilisateur Swagger). La spécification OpenAPI est généré à partir de public/api-docs/openapi.json et couvre les applications (y compris la suspension, reprise, changement de nom de domaine, authentification de base, .env, HTTP auth.json, Artisan / tâches exécutées par l'application, déploiement-config, journaux paginés, redirections www, Octane création et multimoteur engine), alias, déploiement, SSL (installation + force HTTPS), bases de données (liste des moteurs + en option engine sur les mutations), l'état du serveur, l'interrogation des tâches avec structuré result types et schémas d'outils MCP. Version actuelle du package API : 1.20.

Serveur MCP

Un MCP (Model Context Protocol) est exposé à /mcp via Diffusable HTTP. Depuis le forfait API 1.11.1+, un jeton avec le mcp-access la capacité est suffisante pour tout Outils MCP – REST par point de terminaison capacités (apps-view, deploy-manage, apps-basicauth, www-manage, etc.) ne sont pas vérifiés /mcp. Le serveur expose 50+ outils pour l'application, l'alias, www, la base de données, le déploiement, SSL, HTTP Basic Auth, gestion du serveur (PHP, SSH, services, SMTP, santé, liste blanche IP), .env / auth.json / app-run / deploy-config, job polling, logs, Artisan, and server monitoring. Write operations that dispatch async jobs return a job_id — sondage avec JobShow (HTTP 1.11.0+). Les actions d'authentification de base et les outils en lecture seule s'exécutent de manière synchrone.

• Applications : AppList, AppShow, AppCreate (facultatif engine, octane), AppEdit, AppSuspend, AppUnsuspend, AppDelete, AppDeploy, AppDeployRollback, AppDeployUnlock, AppArtisan (Laravel applications uniquement ; rejette les applications personnalisées et tinker), AppEnvShow, AppEnvUpdate, AppAuthJson*, AppRun, AppRunCommands, AppDeployConfigShow, AppDeployConfigUpdate, AppWebhookRecreate (HTTP 1.15.0+ / Cipi 5.0.6+; les outils d'application antérieurs nécessitent API 1.14.0+ / Cipi 5.0.3+)
• Gestion du serveur : PhpList, IpWhitelistShow (API 1.15.0+ / Cipi 5.0.6+)
• HTTP Authentification de base : AppBasicAuthStatus, AppBasicAuthEnable, AppBasicAuthDisable
• Alias : AliasList, AliasAdd, AliasRemove
• WWW / sommet : WwwStatus, WwwAdd, WwwForceToRoot, WwwForceFromRoot, WwwClear (API 1.12.0+)
• Bases de données : DbEngines, DbList, DbCreate, DbDelete, DbBackup, DbRestore, DbPassword (facultatif engine sur liste/mutations ; API 1.12.0+)
• SSL : SslInstall, SslForce (API 1.12.0+)
• Travaux et journaux : JobShow (interroger l'état du travail asynchrone, analysé result, et sortie CLI), AppLogs (journaux d'applications récents par type : all, nginx, php, worker, deploy, laravel — pareil que cipi app logs; Équivalent REST :GET /api/apps/{name}/logs depuis API 1.11.9+), ApiLogShow (journaux Laravel récents pour l'hôte API du panneau)
• Surveillance du serveur : ServerStatus (correspondance JSON structurée GET /api/status / cipi status), ServiceList (état du service du système via cipi service list)

Depuis Cipi 4.6.3, le package du panneau API est mis à jour quotidiennement à 04:30 via /etc/cron.d/cipi-api (cipi api update), donc MCP et les points de terminaison REST restent à jour sans intervention manuelle.

Installation du serveur MCP

Le point de terminaison MCP est facultatif et se charge uniquement lorsque le package MCP requis est installé. Pour l'utiliser de Code VS, Curseur, ou Bureau Claude:

1. Configurez le API avec cipi api <domain> et cipi api ssl
2. Créez un jeton avec cipi api token create et sélectionnez au moinsmcp-access
3. Ajoutez le serveur MCP à votre configuration client (voir ci-dessous)

Curseur

Ajouter à ~/.cursor/mcp.json (ou Curseur → Paramètres → MCP) :

{
  "mcpServers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Le curseur se connecte nativement via HTTP — aucun pont n'est nécessaire.

Code VS

VS Code (avec GitHub Copilot) prend en charge MCP nativement depuis la 1.102. Ajouter à .vscode/mcp.json ou courir MCP : ouvrir la configuration utilisateur pour une configuration globale. Utiliser inputs pour demander le jeton une fois et le stocker en toute sécurité :

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cipi-token",
      "description": "Cipi API Token",
      "password": true
    }
  ],
  "servers": {
    "cipi-api": {
      "type": "http",
      "url": "https://<your-api-domain>/mcp",
      "headers": {
        "Authorization": "Bearer ${input:cipi-token}"
      }
    }
  }
}

Redémarrez VS Code après l’enregistrement. Utiliser MCP : Ajouter un serveur à partir de la palette de commandes pour un configuration guidée.

Claude Code

Ajoutez le serveur MCP directement depuis le CLI :

$ claude mcp add --transport http cipi-api https://<your-api-domain>/mcp \
    --header "Authorization: Bearer <your-token>"

Bureau Claude

Claude Desktop nécessite le mcp-à distance pont pour convertir stdio en HTTP. Ajouter à ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou le équivalent chemin de configuration sur votre système d'exploitation :

{
  "mcpServers": {
    "cipi-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-api-domain>/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Installer mcp-remote une fois avec npm install -g mcp-remote.

Remplacer <your-api-domain> avec votre domaine API (par ex. api.myhosting.com) et <your-token> avec le jeton créé à l'étape 2.

Module WHMCS

Un fonctionnaire Module de provisionnement WHMCS est disponible à github.com/cipi-sh/whmcs. Il relie le cycle de vie de provisionnement WHMCS au Cipi REST API — en automatisant la création d'applications, suppression, certificats SSL, déploiements et modifications de configuration pour vos clients d'hébergement. Aucune dépendance Composer ; le module est un module d'accueil autonome.

Exigences

• WHMCS 8.x (module de provisionnement de type « Serveur »)
• Serveur Cipi avec API activé : cipi api <domain> et cipi api ssl
• Jeton Sanctum Bearer avec les capacités requises :

Mise en place

1. Copier modules/servers/cipi/ dans votre racine WHMCS :

   your-whmcs/
   └── modules/
       └── servers/
           └── cipi/
               ├── cipi.php
               └── lib/
                   └── CipiApiClient.php

2. Dans Administrateur WHMCS → Paramètres système → Serveurs → Ajouter un nouveau serveur:
   • Tapez: Cipi (hébergement Laravel)
   • Nom d'hôte : API URL de base (par ex. https://api.example.com, non barre oblique finale)
   • Mot de passe: Jeton du porteur de cipi api token create
   • Sécurisé: Oui (recommandé — permet la vérification TLS)
3. Créer un produit d'hébergement lié à ce serveur et configurer Module Paramètres:

Types d'applications

Cycle de vie du provisionnement

Suspendre/Reprendre la suspension exiger Cipi 4.5.8+ (suspendre/reprendre la suspension points de terminaison), le package API 1.8.1+, et un jeton avec le apps-suspendcapacité. La suspension remplace le vhost de l'application par une page de maintenance générique HTTP 503 ; la suspension le restaure.

Boutons d'administration

Depuis la vue du service d'administration WHMCS, les opérateurs peuvent déclencher des actions en un clic :

Auto-SSL à la création

Activer Automatique SSL dans les paramètres du module produit pour installer automatiquement un Chiffrons le certificat juste après le provisionnement. Si l'installation de SSL échoue, l'application est toujours créé avec succès et un avertissement est enregistré.

Client API complet

Le groupé CipiApiClient couvre toute la surface Cipi REST API. Même si une fonctionnalité n'est pas connecté à un hook WHMCS, vous pouvez utiliser le client dans des hooks ou des modules complémentaires personnalisés :

Extension du module

// Example: add an alias from a WHMCS hook
require_once ROOTDIR . '/modules/servers/cipi/lib/CipiApiClient.php';

$client = nouveau CipiApiClient('https://api.example.com', $token);
$client->addAlias('monapplication', 'alias.exemple.com');

// Example: create an extra database
$client->createDatabase('monapp_extra');

// Example: backup a database
$client->backupDatabase('monapplication');

Comportement face au client

Le module fait pas ajoutez un onglet Espace client, des boutons personnalisés ou un statut en direct à partir de Cipi. Les clients voient la vue standard du service WHMCS (domaine, statut, dates de renouvellement). Lorsque Cipi provisionne une application qu'il génère secrets ponctuels (Mot de passe SSH, BD mot de passe, clé de déploiement, webhook URL). Le REST API ne transmet pas automatiquement ces secrets dans WHMCS - vous devez étendre le module, écrire un hook ou fournir des informations d'identification via votre flux de travail de support.

Journalisation des modules

Tous les appels API sont enregistrés via logModuleCall()- Créer, résilier, modifier le package, SSL, déploiement, restauration, déverrouillage et informations sur l'application. Activer Utilitaires → Journaux → Module Journal dans WHMCS Admin pour une visibilité complète.

cipi sync

Transférez, répliquez et sauvegardez des applications Laravel entières entre des serveurs Cipi, y compris configuration, sauvegardes de base de données, fichiers de stockage, clés SSH, Workers et crontabs. Chaque archive est crypté avec AES-256-CBC et protégé par une phrase secrète définie par l'utilisateur, donc informations d'identification et les données sensibles sont en sécurité au repos et pendant le transfert.

Présentation des commandes

$ cipi sync export  [app ...] [--with-db] [--with-storage] [--output=<path>] [--passphrase=<secret>]
$ cipi sync import  <archive.tar.gz.enc> [app ...] [--update] [--deploy] [--yes] [--passphrase=<secret>]
$ cipi sync push    [app ...] [--host=IP] [--port=22] [--with-db] [--with-storage] [--import] [--passphrase=<secret>]
$ cipi sync list    <archive.tar.gz.enc> [--passphrase=<secret>]
$ cipi sync pubkey  # display the server's sync public key for inter-server trust
$ cipi sync trust   # add a remote server's public key to cipi's authorized_keys

Cryptage des archives

Toutes les archives de synchronisation sont chiffré par défaut avec AES-256-CBC. Lors de l'exportation, vous êtes vous êtes invité à saisir une phrase secrète (minimum 8 caractères) qui protège l’archive. La même phrase secrète est requis pour l’importer ou l’inspecter. Cela protège les clés SSH, .env fichiers, dumps de base de données, et les informations d'identification au repos et pendant le transfert.

# Interactive mode (default) — prompted for passphrase
$ cipi sync export --with-db
#   Enter passphrase to encrypt the archive: ********
#   Confirm passphrase: ********

# Non-interactive mode — for cron jobs and scripts
$ cipi sync export --with-db --passphrase="MyStr0ngP@ss"

Exporter

Regroupe les configurations d'application dans un fichier crypté .tar.gz.enc archiver. Inclut en option une base de données dumps et fichiers de stockage.

# Export all apps (config only)
$ cipi sync export

# Export three specific apps with database + storage
$ cipi sync export shop blog api --with-db --with-storage

# Export to a custom path (non-interactive)
$ cipi sync export --with-db --output=/root/backups/cipi-march.tar.gz --passphrase="MyStr0ngP@ss"

Ce qui entre dans les archives

Plus les configurations globales : apps.json (filtré sur les applications sélectionnées), databases.json, backup.json, api.json.

Importer

Restaure les applications d'une archive sur le serveur actuel.

# Import all apps from archive
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc

# Import only two apps from an archive that contains ten
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc shop blog --passphrase="MyStr0ngP@ss"

# Import and deploy code from Git immediately
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --deploy

# Non-interactive (skip all prompts)
$ cipi sync import /tmp/cipi-sync-aws01-20260306.tar.gz.enc --yes --passphrase="MyStr0ngP@ss"

Que fait l'importation pour une NOUVELLE application

Lorsqu'une application n'existe pas sur le serveur cible, l'importation la crée à partir de zéro, ce qui équivaut à cipi app create avec toutes les configurations pré-remplies depuis l'archive :

1. Utilisateur Linux — Crée un nouvel utilisateur avec un mot de passe aléatoire
2. Annuaires — Crée /home/<app>/shared/, logs/, .ssh/, .deployer/
3. Clé de déploiement SSH — Restaurations à partir des archives (la même clé fonctionne avec GitHub/GitLab sans reconfiguration)
4. Base de données MariaDB — Crée une base de données + un utilisateur avec un nouveau aléatoire mot de passe
5. Données de la base de données— Importe le dump si --with-db a été utilisé pendant exporter
6. .env — Copies d'archives, puis écrase DB_PASSWORD, DB_USERNAME, DB_DATABASE, DB_HOST avec les valeurs du nouveau serveur. Tout le reste (APP_KEY, MAIL_*, REDIS_*, variables personnalisées) reste tel quel
7. Pool PHP-FPM, hôte virtuel Nginx, travailleurs Supervisor, Crontab, déployeur — Entièrement configuré à partir des données d'archive

Contrôles de sécurité avant l'importation

L'importation effectue des vérifications préalables au vol avant de toucher à quoi que ce soit :

• L'application existe déjà — bloqué sauf si --update est passé
• Conflit de domaine — bloqué si une autre application utilise déjà le même domaine
• Version PHP manquante — avertissement (l'application est ignorée ; installez d'abord la version avec cipi php install)

Mode de mise à jour (--update)

La caractéristique clé pour synchronisation répétée (par exemple, réplication par basculement). Sans --update, l'importation refuse de toucher aux applications qui existent déjà. Avec --update, il mises à jour applications existantes et crée des nouveaux.

$ cipi sync import /tmp/archive.tar.gz.enc --update --passphrase="MyStr0ngP@ss"

Que fait la mise à jour pour une application existante

• .env synchroniser — Les archives .env remplace le local, mais DB_PASSWORD, DB_USERNAME, DB_DATABASE, et DB_HOST sont préservé du serveur local. Tout le reste (APP_KEY, MAIL_*, REDIS_*, variables personnalisées) provient du source.
• Données de la base de données — Si l'archive a un dump, supprime toutes les tables (avec SET FOREIGN_KEY_CHECKS=0) et les réimportations. Utilise les informations d'identification racine locales.
• Stockage — Si l'archive dispose d'un stockage, extrait sur le répertoire existant (nouveau fichiers ajoutés, existants écrasés).
• Migration de version PHP — Si la source utilise une version PHP différente, la mise à jour migre le pool FPM, supervisor, crontab, le déployeur et .env automatiquement.
• Nginx vhost, Supervisor Workers, configuration du déployeur — Régénéré à partir des archives données.
• Déployer — Si --deploy est passé, court dep deploy à tirer dernier code.

Quelle mise à jour ne change PAS

• Mot de passe utilisateur Linux
• Clés de déploiement SSH (conservées depuis la première importation)
• MariaDB identifiants utilisateur (la cible conserve les siens)
• SSL certificats (exécuter cipi ssl install séparément)

Liste (inspecter les archives)

Visualisez le contenu d'une archive sans rien importer.

$ cipi sync list /tmp/cipi-sync-aws01-20260306.tar.gz.enc --passphrase="MyStr0ngP@ss"

Cipi Synchroniser les archives
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Cipi v5.0.18
  Exporté le 2026-03-06T15:00:00Z
  Source aws01 (3.120.xx.xx)
  Base de données vrai
  Stockage vrai
 
  Applications
  DOMAINE D'APPLICATION PHP STOCKAGE DE BD
  shop shop.example.com 8.4 oui oui
  blog blog.example.com 8.4 oui oui
  api api.example.com 8,5 oui oui
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Push (export + transfert + import)

Combine l'exportation, le transfert rsync et l'importation à distance en une seule commande. Fonctionne entièrement à partir du source serveur.

# Interactive push — prompted for target IP and passphrase
$ cipi sync push --with-db --with-storage --import

# Non-interactive push (for cron and scripts)
$ cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="MyStr0ngP@ss"

# Push specific apps only
$ cipi sync push shop blog --host=51.195.xx.xx --with-db --import --passphrase="MyStr0ngP@ss"

# Push without auto-import (transfer only — import manually on remote)
$ cipi sync push --host=51.195.xx.xx --with-db --passphrase="MyStr0ngP@ss"

Comment fonctionne le push

1. Étape 1 : Fonctionne cipi sync export localement (chiffre avec une phrase secrète)
2. Étape 2 : Transfère l'archive chiffrée vers la cible via rsync
3. Étape 3 : Si --import est passé, court cipi sync import --update --yes sur la cible via SSH

Push ajoute toujours --update et --yes lors de l'appel de l'importation sur la télécommande. Ceci signifie : la première exécution crée toutes les applications, les exécutions suivantes les mettent à jour progressivement. C'est ce qui fait pousser peut être exécuté en toute sécurité à plusieurs reprises via cron.

Configuration SSH pour push

Le serveur source a besoin d'un accès SSH à la cible en tant que cipiutilisateur. Utilisez le mécanisme de confiance pour l'authentification sans mot de passe et basée sur une clé entre les serveurs Cipi :

# On the SOURCE server — display its sync public key
$ cipi sync pubkey

# On the TARGET server — add the source's public key to cipi's authorized_keys
$ cipi sync trust

Une fois digne de confiance, cipi sync push se connecte comme le cipi l'utilisateur automatiquement — aucun accès root requis.

Scénarios pratiques

Scénario 1 : Migrer toutes les applications d'AWS vers OVH

Vous disposez de 20 applications sur AWS. Vous avez acheté un OVH VPS et installé Cipi dessus.

# On AWS (source server)
$ cipi sync push --host=51.195.xx.xx --with-db --with-storage --import

Sur la cible OVH : 20 utilisateurs Linux, 20 bases de données, 20 vhosts nginx, pools PHP-FPM, configs supervisor, crontabs – tous créés automatiquement. Données de base de données importées, stockage extrait, .env fichiers copié avec les mots de passe DB d'OVH, clés de déploiement SSH conservées (les mêmes clés fonctionnent avec GitHub). Après importer, installez SSL et mettez à jour DNS :

# On OVH (target server)
$ cipi ssl install shop
$ cipi ssl install blog
# ... then update DNS A records to OVH IP

Scénario 2 : Réplication de basculement planifiée (cron)

Toutes les 6 heures, le serveur 1 synchronise toutes les applications avec le serveur 2. Si le serveur 1 tombe en panne, modifiez DNS et continuez en direct. Serveur 2.

# One-time setup on Server 1 — trust Server 2 using cipi sync trust
$ cipi sync pubkey  # copy this key, then run "cipi sync trust" on Server 2
$ echo "YourStr0ngPassphrase!" > /etc/cipi/.sync_passphrase
$ chmod 400 /etc/cipi/.sync_passphrase

# First push (manual, to verify)
$ cipi sync push --host=server2-ip --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)"

# Add to crontab for automatic replication
$ crontab -e

0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --port=22 --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-replica.log 2>&1

La fenêtre de perte de données est égale à l'intervalle cron (6 heures dans cet exemple). Lorsque le serveur 1 tombe en panne : changez DNS sur le serveur 2, exécutez cipi ssl install pour chaque application, et vous êtes en direct.

Scénario 3 : Répliquer sur plusieurs serveurs

# Stagger by 30 minutes so exports don't run simultaneously
0 */6 * * * /usr/local/bin/cipi sync push --host=51.195.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-ovh.log 2>&1
30 */6 * * * /usr/local/bin/cipi sync push --host=164.90.xx.xx --with-db --with-storage --import --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/sync-do.log 2>&1

Scénario 4 : Sauvegarde cryptée quotidienne (pas de transfert)

0 3 * * * /usr/local/bin/cipi sync export --with-db --with-storage --output=/root/backups/cipi-$(date +\%Y\%m\%d).tar.gz --passphrase="$(cat /etc/cipi/.sync_passphrase)" >> /var/log/cipi/export.log 2>&1

Crée une archive portable cryptée chaque nuit. Restaurez sur n'importe quel serveur Cipi à tout moment avec cipi sync import.

Limites

• SSL certificats ne sont pas inclus dans les archives. Courir cipi ssl install après importation sur un nouveau serveur.
• La synchronisation de la base de données est entièrement remplacée, pas incrémentiel. Chaque mise à jour supprime toutes les tables et réimportations.
• La synchronisation du stockage est un extrait complet, pas rsync incrémentiel. Fichiers supprimés sur le source rester sur la cible.
• Déployer les clés sont les mêmes sur la source et la cible — non GitHub/GitLab reconfiguration nécessaire.

Coffre-fort et chiffrement

Cipi chiffre tous les fichiers de configuration au repos en utilisant AES-256-CBC. Le système Vault fournit un cryptage et un déchiffrement transparents afin que les données sensibles — mots de passe de base de données, API des jetons, Clés SSH, .env contenu - n'est jamais stocké en texte brut sur le disque.

Architecture

Le système est construit sur deux couches :

• Coffre-fort — cryptage transparent des fichiers de configuration JSON sur le disque (server.json, apps.json, databases.json, backup.json, smtp.json, api.json)
• Synchroniser le cryptage — cryptage basé sur une phrase secrète des archives d'exportation pour une sécurité transfert entre serveurs

Comment fonctionne Vault

Une clé principale est générée lors de l'installation avec openssl rand -base64 32 et stocké à /etc/cipi/.vault_key (chmod 400, racine uniquement). Chaque fichier de configuration JSON est chiffré sur le disque avec openssl enc -aes-256-cbc -salt -pbkdf2. Les fichiers conservent le .json extension - le contenu est simplement un blob crypté au lieu de JSON lisible.

Le vault_read La fonction détecte automatiquement si un fichier est en texte brut ou crypté (en arrière compatibilité), de sorte que les serveurs existants migrent de manière transparente lors de la mise à jour.

Fonctions du coffre-fort

# Core functions in lib/vault.sh
vault_init          # Generate .vault_key if not present
vault_read <file>   # Decrypt and output JSON to stdout (auto-detect plain/encrypted)
vault_write <file>  # Read JSON from stdin, encrypt and write to disk
vault_seal <file>   # Encrypt an existing plaintext file in-place
vault_get <file> <jq_query>  # Shortcut: vault_read | jq

Projection publique

Cipi génère un apps-public.json fichier contenant uniquement des champs non sensibles (domaine, alias, version PHP, branche, référentiel, utilisateur, horodatage de création, plus suspended et basic_auth drapeaux). Le cipi-api lectures de groupe cette projection en texte brut au lieu du fichier crypté, gardant la clé du coffre-fort limitée à root.

Synchroniser le chiffrement des archives

Quand tu cours cipi sync export, les configurations sont déchiffrées du coffre-fort vers une zone de transit, alors l'intégralité de l'archive est cryptée avec votre phrase secrète. A l'import, l'archive est déchiffrée avec la phrase secrète et les configurations sont rechiffrées avec le coffre-fort du serveur de destination clé.

Notifications par courrier électronique

Cipi peut envoyer des alertes par e-mail en cas d'erreurs de sauvegarde, d'échecs de déploiement, d'échecs de tâches cron du système ou des événements d'authentification liés à la sécurité se produisent. La configuration SMTP est stockée cryptée dans /etc/cipi/smtp.json et inclus dans la synchronisation exportations.

Commandes

$ cipi smtp configure      # interactive setup (Gmail, SendGrid, Mailgun, custom)
$ cipi smtp status          # display current notification settings
$ cipi smtp test            # send a verification email
$ cipi smtp enable          # enable notifications
$ cipi smtp disable         # disable without losing settings
$ cipi smtp delete          # remove SMTP configuration entirely

# Non-interactive (v5.0.6+) — panel API, scripts, automation
$ cipi smtp configure --host=smtp.example.com --port=587 --user=… --password=… \
    --from=alerts@example.com --to=ops@example.com --tls=on
$ cipi smtp status --json
$ cipi smtp delete --force

Déclencheurs de notification granulaires

Depuis v4.6.3, vous pouvez contrôler les événements qui envoient des e-mails lorsque SMTP est configuré. Tous les déclencheurs sont activé par défaut; les événements sont toujours enregistrés /var/log/cipi/events.log indépendamment de.

$ cipi notifications list              # all triggers grouped by category
$ cipi notifications enable <trigger>   # turn one trigger on
$ cipi notifications disable <trigger>  # turn one trigger off
$ cipi notifications enable-all          # re-enable everything
$ cipi notifications disable-all         # mute all email alerts
$ cipi notifications reset               # restore defaults (all on)

Configuration : /etc/cipi/notifications.json. Courir cipi notifications list sur le serveur pour l'état marche/arrêt en direct. ID de déclencheur pour cipi notifications enable|disable <trigger>:

Alertes automatiques

Une fois configuré, Cipi envoie des notifications par e-mail sur :

• Erreurs de sauvegarde (échecs de téléchargement S3, erreurs de vidage)
• Échecs de déploiement (erreurs de déploiement, déclencheurs de restauration)
• Échecs de tâche du système cron (via le cipi-cron-notify emballage)
• Événements du cycle de vie de l'application : avertit lorsqu'une application est créée, modifiée ou supprimée, y compris nom d'hôte du serveur, nom de l'application, domaine et version PHP
• Sudo et su altitude — avertit lorsqu'un utilisateur réussit à élever via sudo ou su, y compris qui l'a exécuté, l'utilisateur cible (par exemple su), Clé SSH, adresse IP client et TTY
• Connexion SSH privilégiée : avertit quand root ou tout sudoer se connecte via SSH, y compris l'adresse IP source, l'empreinte digitale de la clé SSH et le commentaire clé
• Modifications de la clé SSH — avertit lorsqu'une clé SSH est ajoutée, supprimée ou renommée sur le cipi utilisateur, y compris le nom d'hôte, l'adresse IP, l'empreinte digitale, le commentaire clé, l'horodatage et nombre de clés restant. Les alertes de renommage incluent également l’ancien et le nouveau nom de clé.

Chaque notification par e-mail comprend un pied de page avec l'adresse IP du client (SSH_CLIENT) et le SSH nom de clé utilisé pour l'authentification, le cas échéant. Le nom de la clé est résolu via SSH_USER_AUTH avec un auth.log repli en cas de besoin.

Notifications d'authentification de sécurité

Cipi intègre les notifications d'authentification basées sur PAM via pam_exec.so avec ExposeAuthInfo activé. Lorsque SMTP est configuré, le le système envoie automatiquement des alertes par e-mail sur ces événements liés à la sécurité :

• Sudo et su élévation - déclenché lorsqu'un utilisateur exécute avec succès sudo ou su. La notification comprend le nom d'utilisateur, l'utilisateur cible (par exemple su), le TTY, la clé SSH, l'adresse IP du client et l'horodatage.
• Connexion SSH privilégiée - déclenché lorsque root ou tout utilisateur du sudo le groupe se connecte via SSH. La notification comprend le nom d'utilisateur, l'adresse IP source adresse, empreinte digitale de la clé SSH et commentaire clé (résolu à partir de /var/log/auth.log correspondance d'empreintes digitales avec authorized_keys).
• Modifications de la clé SSH - déclenché lorsqu'une clé SSH est ajoutée, supprimée ou renommé sur le cipi utilisateur via cipi ssh add, cipi ssh remove, ou cipi ssh rename. La notification comprend le nom d'hôte, adresse IP du serveur, empreinte digitale de clé, commentaire de clé, horodatage et nombre de clés restantes. Renommer les alertes incluent également l’ancien et le nouveau nom de clé.
• Événements du cycle de vie des applications- déclenché lorsqu'une application est créée, modifiée ou supprimée. La notification inclut le nom d'hôte du serveur, le nom de l'application, le domaine et la version PHP.

Les notifications s'exécutent de manière asynchrone en arrière-plan afin de ne jamais retarder la connexion ou la commande exécution. Si SMTP n'est pas configuré, les hooks échouent silencieusement sans impact sur le système.

Journal des événements de sécurité

Quelle que soit la configuration SMTP, tous les événements de notification (modifications de clé SSH, cycle de vie des applications, réinitialisations de mot de passe, connexion sudo/su/SSH, échecs cron) sont toujours enregistrés dans /var/log/cipi/events.log dans un format compact d’une seule ligne. Le journal est tourné quotidiennement avec Rétention d'un an via logrotate.

Cron emballage

Le cipi-cron-notify l'utilitaire encapsule les tâches système cron et envoie une notification si la tâche sort avec un code différent de zéro. Ceci est utile pour surveiller les tâches planifiées critiques.

Conservation des journaux (RGPD)

Cipi applique des politiques de rotation automatique des journaux conçues pour respecter le RGPD et la protection générale des données. exigences. Les journaux sont alternés et supprimés automatiquement — aucun nettoyage manuel n'est nécessaire.

Valkey

HTTP est le magasin de données en mémoire que Cipi installe dans le cadre de la pile par défaut. Depuis v4.5.6 Cipi dispositions Valkey au lieu de redis-server. Il excelle dans la mise en cache, le stockage de sessions, les files d'attente de messages, le temps réel diffusion et limitation du débit.

Pourquoi Valkey au lieu de Redis

Valkey est le vraiment open-source, sous licence BSD fourchette de Redis, gérée par le Fondation Linux. Il a été créé en 2024 après que Redis Inc. ait renouvelé la licence de Redis. de la licence BSD permissive au SSPL / RSALv2 disponible en source - un changement qui n'est plus respecté la définition open-source. Soutenu par AWS, Google Cloud, Oracle et une large communauté, Valkey continue la même base de code testée au combat sous une licence qui restelibre pour toujours. Cela en fait un ajustement parfait pour la philosophie MIT de Cipi, sans verrouillage du fournisseur, et il est livré nativement dans le référentiel Universe de Ubuntu 24.04 (forfaits valkey-server + valkey-tools) — aucun PPA tiers auquel faire confiance.

Tout aussi important, Valkey est un remplacement immédiat: ça parle exactement la même chose RESP protocole sur le même port (127.0.0.1:6379), honore le même requirepass / bind directives et lit le même format de données RDB/AOF. Votre les applications ont besoin zéro changement — le phpredis extension et votre existant REDIS_* .env les valeurs continuent de fonctionner exactement comme avant.

Comment Cipi l'implémente

• Installer — setup.sh installe et configure Valkey (/etc/valkey/valkey.conf, service valkey-server), lié à localhost uniquement et protégé par un mot de passe.
• Gestion des services — cipi service … gère valkey-server (les noms redis-server, redis, et valkey sont toujours acceptés comme pseudonymes). Il est ajouté aux mises à niveau sans surveillance liste noire, donc Cipi la gère au lieu d'une mise à niveau automatique.
• Informations d'identification — stocké sous valkey_user / valkey_password dans /etc/cipi/server.json (l'héritage redis_* les clés sont toujours lues comme solution de secours). Hôte : 127.0.0.1, Port : 6379.
• Réinitialisation du mot de passe — cipi reset valkey-password régénère le mot de passe et redémarre le service (cipi reset redis-password reste comme alias).

Migration depuis Redis (4.5.6 / 4.5.7)

Les serveurs existants sont automatiquement basculés sur Valkey cipi self-update - pas d'application .env édition requise. La migration réutilise le mot de passe Redis actuel (récupéré à partir de server.json ou /etc/redis/redis.conf), force un RDB SAVE et instantanés dump.rdb/AOF, purges redis-server, installe valkey-server + valkey-tools sur le même port avec le même requirepass / bind, restaure l'ensemble de données et réécrit server.json (redis_* → valkey_*) et les mises à niveau sans surveillance liste noire : le cache, les sessions et les tâches en file d'attente survivent au changement.

v4.5.7 corrige le nom du package en valkey-server (le Ubuntu 24.04 paquet démon; 4.5.6 initialement utilisé valkey) et effectue la migration entièrement autonome et sécuritaire. Il active automatiquement leuniverse Composant APT lorsque le package n'est pas trouvé, exécute une vérification de l'état après le démarrage (PING → PONG avec le mot de passe), et revient à redis-server— restaurer à la fois les fichiers sauvegardés le mot de passe et l'ensemble de données - si Valkey ne peut pas être installé ou n'est pas sain. L'ensemble de données l'instantané est conservé jusqu'à ce que le commutateur soit vérifié, puis nettoyé. La migration est idempotente : les serveurs déjà sur Valkey, ignorez-le.

Laravel intégration

Ajoutez ces variables à votre .env via cipi app env myapp. Les noms de variables rester REDIS_* — c'est quoi phpredis et Laravel redis le pilote attend, et Valkey répond sur le même socket :

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=votre-mot de passe-du-serveur-json
REDIS_PORT=6379

Définissez ensuite les pilotes pour chaque cas d'utilisation :

• Cache — CACHE_STORE=redis
• Séance — SESSION_DRIVER=redis
• File d'attente — QUEUE_CONNECTION=redis (puis cipi worker restart myapp)
• Diffusion — BROADCAST_CONNECTION=redis

Installez le phpredis Extension PHP pour de meilleures performances, ou utilisez predis/predis comme solution de repli pure-PHP. Les deux parlent à Valkey de manière transparente.

Mise à jour automatique

Cipi peut se mettre à jour à partir de GitHub sans affecter aucune application, base de données ou configuration.

$ cipi self-update --check   # check for a new version
$ cipi self-update           # update to latest

Processus de mise à jour

1. Télécharge la dernière version depuis GitHub
2. Sauvegarde l'installation actuelle sur /opt/cipi.bak.YYYYMMDDHHMMSS/
3. Remplace CLI et les scripts lib
4. Exécute tout en attente scripts de migration dans l'ordre (par exemple, nouvelles directives Nginx, nouvelles forfaits)
5. Met à jour le fichier de version

Les scripts de migration résident dans lib/migrations/ et sont nommés par version (par ex. 4.1.0.sh, 5.0.18.sh). Lors de la mise à jour de la v4.0.0 vers la v4.2.0, Cipi s'exécute automatiquement 4.1.0.sh et 4.2.0.sh en ordre. Vos applications, bases de données et configurations ne sont jamais touchés.

Récent 5.0.x les migrations améliorent la fiabilité sans modifier les données de l'application : 5.0.6 — fichier de liste blanche IP par défaut et sudoers API régénérés ; 5.0.9 — cipi php switch dans les sudoers pour PUT /api/php/default; 5.0.13 — récupérer la propriété API/GUI après la mise à jour ; 5.0.14–5.0.17 - mises à jour chronométrées du package du panneau GitHub/Packagist (plus de blocage cipi self-update sur les clones API/GUI Composer VCS );5.0.18 — réparer le panneau GUI après le lien symbolique/open_basedir HTTP 500 (cipi gui fix-permissions). Courir cipi self-update atteindre 5.0.18.

Par exemple, le 4.5.5 migration modernise les applications existantes avec la nouvelle ll='ls -al' Alias du shell : il ajoute l'alias à l'alias de chaque application ~/.bashrc une fois (uniquement en cas d'absence, en préservant la propriété), afin que les applications créées avant la version 4.5.5 l'obtiennent au prochain cipi self-update.

Crons de maintenance automatique

Cipi planifie plusieurs tâches au niveau racine pendant l'installation. Crontabs au niveau de l'application (planificateur, déploiement déclencheur) sont distincts — voir Crontab utilisateur.

Domaines génériques

Cipi fait pas prend en charge les domaines génériques (*.myapp.com) nativement. Le Le bloc est double et architectural – pas un détail de configuration.

Pourquoi les caractères génériques ne sont pas pris en charge

1 — Rejets de validation de domaine *
Chaque domaine transmis à cipi alias add (et cipi app create) est validé contre une expression rationnelle stricte qui exige que la chaîne commence par [a-zA-Z0-9]. L'astérisque échoue immédiatement, avant que nginx ou certbot ne soient touchés.

2 — Certbot utilise le défi HTTP-01, qui ne peut pas émettre de certificats génériques
cipi ssl install appels certbot --nginx, qui s'appuie sur le HTTP-01 (ou TLS-ALPN-01) : placer un fichier de vérification sur le disque et le servir sur le port 80. Allons Encrypt émet uniquement des certificats génériques via le Défi DNS-01, ce qui nécessite accès par programmation au API de votre fournisseur DNS. Cipi ne s'intègre à aucun fournisseur DNS, donc même si la validation était contournée, certbot refuserait de délivrer le certificat générique.

Alternative recommandée — Certificat multi-SAN

Si vos sous-domaines sont fixes et énumérables (par ex. api, admin, www, staging), l'approche correcte consiste à ajouter chacun d'entre eux de manière explicite alias et laissez Cipi émettre un seul certificat SAN les couvrant tous :

$ cipi alias add myapp api.myapp.com
$ cipi alias add myapp admin.myapp.com
$ cipi alias add myapp www.myapp.com
$ cipi ssl install myapp   # single cert, SAN covers all domains

Certbot --expand L'indicateur (utilisé en interne par Cipi) ajoute les nouveaux SAN aux réseaux existants. certificat sans en délivrer un nouveau. La liste SAN n'a pas de limite significative pour une utilisation typique.

Certificat générique manuel (en dehors de Cipi)

Si vous avez besoin de sous-domaines dynamiques (par ex. <tenant>.saas.com), vous pouvez obtenir un joker certificat manuellement à l’aide d’un plugin DNS pour certbot et placez-le sur le serveur. Cipi ne gérez-le, renouvelez-le ou suivez-le : vous êtes entièrement propriétaire du cycle de vie.

# example with the Cloudflare DNS plugin
$ pip install certbot-dns-cloudflare
$ certbot certonly --dns-cloudflare \
    --dns-cloudflare-credentials /root/.cloudflare.ini \
    -d "*.myapp.com" -d "myapp.com"

Après avoir obtenu le certificat, modifiez directement le vhost nginx pour l'application (/etc/nginx/sites-available/myapp) pour référencer les chemins de certificat génériques et ajouter server_name *.myapp.com myapp.com;. Rechargez ensuite nginx :

$ nginx -t && systemctl reload nginx

Modifier la configuration Nginx

Pour personnaliser le vhost Nginx pour une application, modifiez directement la configuration du site. Après modifications, testez et rechargez Nginx.

$ sudo nano /etc/nginx/sites-available/<app>
$ sudo nginx -t && sudo systemctl reload nginx

Désinstaller Cipi

Cipi ne fournit pas de commande de désinstallation intégrée. Si vous devez supprimer complètement Cipi d'un serveur, suivez les étapes ci-dessous dans l'ordre. Cette procédure supprime tous les composants qui Cipi installations – utilisateurs, services, packages, configurations et données.

1 — Arrêtez et supprimez toutes les applications

Pour chaque application gérée par Cipi, supprimez son utilisateur système, son répertoire personnel, sa base de données, son hôte virtuel nginx, PHP-FPM. piscine, et la configuration supervisor.

# List all app users (members of cipi-apps group)
$ grep cipi-apps /etc/group

# For EACH app user, remove everything
$ supervisorctl stop <app_user>:*
$ rm -f /etc/supervisor/conf.d/<app_user>.conf
$ rm -f /etc/nginx/sites-enabled/<app_user>
$ rm -f /etc/nginx/sites-available/<app_user>
$ rm -f /etc/php/*/fpm/pool.d/<app_user>.conf
$ rm -f /etc/sudoers.d/cipi-<app_user>
$ mysql -e "DROP DATABASE IF EXISTS <app_user>; DROP USER IF EXISTS '<app_user>'@'localhost'; DROP USER IF EXISTS '<app_user>'@'127.0.0.1';"
$ userdel -r <app_user>

2 — Supprimez l'utilisateur et les groupes Cipi

$ userdel -r cipi
$ groupdel cipi-ssh 2>/dev/null
$ groupdel cipi-apps 2>/dev/null

3 — Supprimez les binaires, les bibliothèques et les données Cipi

$ rm -f /usr/local/bin/cipi
$ rm -f /usr/local/bin/cipi-worker
$ rm -f /usr/local/bin/cipi-cron-notify
$ rm -f /usr/local/bin/cipi-auth-notify
$ rm -rf /opt/cipi
$ rm -rf /etc/cipi
$ rm -rf /var/log/cipi

4 — Supprimez Cipi API (si installé)

$ systemctl stop cipi-queue 2>/dev/null
$ systemctl disable cipi-queue 2>/dev/null
$ rm -f /etc/systemd/system/cipi-queue.service
$ systemctl daemon-reload

5 — Supprimer les tâches Cipi cron

# Edit root crontab and remove all Cipi entries
$ crontab -e
# Remove lines referencing: cipi self-update, certbot renewal, cache cleanup, RAM drop

6 — Supprimer les fichiers de configuration Cipi

# Sudoers
$ rm -f /etc/sudoers.d/cipi-sudo
$ rm -f /etc/sudoers.d/cipi-api

# Logrotate
$ rm -f /etc/logrotate.d/cipi-app-logs
$ rm -f /etc/logrotate.d/cipi-http-logs
$ rm -f /etc/logrotate.d/cipi-security-logs

# Unattended upgrades
$ rm -f /etc/apt/apt.conf.d/50cipi-unattended-upgrades
$ rm -f /etc/apt/apt.conf.d/20cipi-auto-upgrades

# System profile and MOTD
$ rm -f /etc/profile.d/cipi-env.sh
$ echo "" > /etc/motd

# MariaDB custom config
$ rm -f /etc/mysql/mariadb.conf.d/99-cipi.cnf

# PHP custom config (all versions)
$ rm -f /etc/php/*/fpm/conf.d/99-cipi.ini

# Nginx default page
$ rm -f /etc/nginx/sites-available/default
$ rm -f /etc/nginx/sites-enabled/default

7 — Purger les packages installés

Supprimez tous les packages installés par Cipi. Ignorez tout package que vous souhaitez conserver à d’autres fins.

$ systemctl stop nginx mariadb valkey-server fail2ban supervisor
$ systemctl stop php*-fpm

$ apt purge -y nginx* mariadb-server mariadb-client valkey-server \
    fail2ban supervisor certbot python3-certbot-nginx \
    php8.4* php8.5* nodejs

$ apt autoremove -y
$ apt autoclean

8 — Supprimer les référentiels APT

$ add-apt-repository --remove ppa:ondrej/php -y
$ rm -f /etc/apt/sources.list.d/mariadb.list
$ rm -f /etc/apt/sources.list.d/nodesource.list
$ rm -f /etc/apt/keyrings/mariadb-keyring.pgp
$ apt update

9 — Supprimez Composer et le déployeur

$ rm -f /usr/local/bin/composer
$ rm -f /usr/local/bin/dep

10 — Supprimer le fichier d'échange

$ swapoff /var/swap.1
$ rm -f /var/swap.1
# Remove the swap entry from /etc/fstab
$ sed -i '/swap\.1/d' /etc/fstab

11 — Restaurer les paramètres par défaut de SSH et PAM

Cipi renforce SSH (désactive la connexion root et l'authentification par mot de passe) et ajoute des hooks PAM. Si vous devez restaurer valeurs par défaut :

# Restore sshd_config to allow password auth (if needed)
$ sed -i 's/^PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config
$ sed -i 's/^PermitRootLogin no/PermitRootLogin yes/' /etc/ssh/sshd_config

# Remove Cipi PAM hooks
$ sed -i '/cipi-auth-notify/d' /etc/pam.d/sshd
$ sed -i '/cipi-auth-notify/d' /etc/pam.d/sudo

# Restore sysctl
$ sed -i '/vm.swappiness/d' /etc/sysctl.conf
$ sysctl -p

$ systemctl restart sshd

12 — Réinitialiser le pare-feu

$ ufw disable
$ ufw reset