API d'import de site

L'API d'import de site crée un site complet — projet, base de données, application, variables d'environnement et domaine — en un seul appel. Elle est pensée pour les scripts de migration et les outils d'automatisation qui doivent créer des sites par programme.

Prérequis

Une clé d'API (Account → API Keys dans le tableau de bord). Basculez sur l'organisation visée avant de la créer : la clé est liée à l'organisation active au moment de sa création.
L'identifiant de votre organisation (visible dans l'URL lorsque vous la consultez)
Un fournisseur Git configuré (Settings → Git Providers) si vous partez d'une source GitHub ou GitLab
Un registre de conteneurs — soit configuré dans Settings → Registry, soit fourni par défaut par l'administrateur de la plateforme

Démarrage rapide

export API_KEY="votre-cle-api"
export KUPLOY_URL="https://votre-instance-kuploy.com"

# Prévisualisation (sans rien créer)
curl -X POST $KUPLOY_URL/api/site-import/preview \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_xxx",
    "name": "monsite",
    "domain": "monsite.com",
    "database": {"type": "mariadb", "name": "monsite", "user": "monsite", "password": "secret"},
    "source": {"type": "github", "repo": "monorg/sites", "branch": "main", "buildPath": "/monsite", "buildType": "dockerfile", "githubId": "gh_xxx"}
  }'

# Import (crée tout)
curl -X POST $KUPLOY_URL/api/site-import \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_xxx",
    "name": "monsite",
    "domain": "monsite.com",
    "database": {"type": "mariadb", "name": "monsite", "user": "monsite", "password": "secret"},
    "source": {"type": "github", "repo": "monorg/sites", "branch": "main", "buildPath": "/monsite", "buildType": "dockerfile", "githubId": "gh_xxx"},
    "envVars": {"APP_KEY": "base64:xxx", "APP_ENV": "production"},
    "port": 80
  }'

# Consulter l'état
curl $KUPLOY_URL/api/site-import/imp_xxx \
  -H "Authorization: Bearer $API_KEY"

Authentification

Créez une clé d'API depuis Account → API Keys (voir Clés d'API). Le secret n'est affiché qu'une seule fois, à la création. Transmettez-le par l'un ou l'autre en-tête :

Authorization: Bearer <votre-cle-api>
x-api-key: <votre-cle-api>

Une clé d'API hérite de vos droits. Si vous êtes propriétaire d'une organisation, la clé peut y créer des ressources.

astuce

Au moment de créer la clé, renseignez l'organisation dans ses métadonnées pour qu'elle soit bien rattachée à la bonne.

Les points d'accès

`POST /api/site-import` — importer un site

Crée le projet, la base de données, l'application, les variables d'environnement et le domaine en un appel.

Corps de la requête :

Champ	Type	Obligatoire	Description
`organizationId`	string	Oui	L'organisation visée
`name`	string	Oui	Le nom du projet et de l'application
`domain`	string	Non	Domaine personnalisé (par exemple `monsite.com`)
`database`	object	Non	La configuration de la base de données
`database.type`	enum	Oui (si base)	`mariadb`, `mysql`, `postgres`, `mongodb`
`database.name`	string	Oui (si base)	Le nom de la base
`database.user`	string	Oui (si base)	L'utilisateur de la base
`database.password`	string	Oui (si base)	Le mot de passe de la base
`source`	object	Oui	La configuration de la source applicative
`source.type`	enum	Oui	`github`, `gitlab`, `docker`, `git`
`source.repo`	string	Si github/gitlab	Le dépôt, au format `propriétaire/nom`
`source.branch`	string	Non	La branche (par défaut : `main`)
`source.buildPath`	string	Non	Le sous-répertoire servant de contexte de build (par défaut : `/`)
`source.buildType`	enum	Non	`dockerfile` ou `nixpacks` (par défaut : `dockerfile`)
`source.dockerImage`	string	Si docker	L'image Docker à déployer
`source.githubId`	string	Si github	L'identifiant de votre fournisseur Git GitHub configuré
`source.gitlabId`	string	Si gitlab	L'identifiant de votre fournisseur Git GitLab configuré
`source.customGitUrl`	string	Si git	L'URL de clonage, en HTTPS ou SSH
`source.customGitSSHKeyId`	string	Non	L'identifiant de clé SSH, pour un dépôt privé
`envVars`	object	Non	Un dictionnaire clé-valeur de variables d'environnement
`port`	number	Non	Le port de l'application (par défaut : `80`)

Réponse :

{
  "importId": "abc123",
  "status": "success",
  "projectId": "proj_xxx",
  "applicationId": "app_xxx",
  "databaseId": "db_xxx",
  "databaseType": "mariadb",
  "databaseServiceHost": "monsite-db-a2b3c4",
  "domainId": "dom_xxx"
}

Valeurs possibles du statut : success, failed, partial — certaines ressources ont été créées avant l'échec.

`POST /api/site-import/preview` — prévisualiser

Mêmes paramètres que l'import. Renvoie le résultat de la validation sans rien créer :

{
  "valid": true,
  "resources": {
    "project": { "name": "monsite" },
    "database": { "type": "mariadb", "name": "monsite" },
    "application": { "name": "monsite", "sourceType": "github", "buildType": "dockerfile" },
    "domain": { "host": "monsite.com" }
  },
  "warnings": [],
  "errors": []
}

Servez-vous-en pour valider avant d'importer. La prévisualisation vérifie les conflits de noms, la disponibilité du domaine et la configuration de la source.

`GET /api/site-import` — lister les imports

Renvoie l'historique des imports de votre organisation.

Paramètres de requête : limit (50 par défaut, 100 au maximum), offset (0 par défaut).

`GET /api/site-import/:id` — consulter un import

Renvoie le détail d'un import : son statut, les identifiants des ressources créées et les informations d'erreur.

Les types de source

GitHub

Exige un fournisseur Git GitHub configuré dans votre organisation. Son identifiant se trouve dans Settings → Git Providers.

{
  "source": {
    "type": "github",
    "repo": "monorg/mondepot",
    "branch": "main",
    "buildPath": "/monsite",
    "buildType": "dockerfile",
    "githubId": "gh_xxx"
  }
}

Git personnalisé (HTTPS ou SSH)

Pour les dépôts qui ne sont pas connectés par OAuth. Fonctionne avec n'importe quel hébergeur Git.

{
  "source": {
    "type": "git",
    "customGitUrl": "https://github.com/monorg/mondepot.git",
    "branch": "main",
    "buildPath": "/monsite",
    "buildType": "dockerfile"
  }
}

Pour un dépôt privé, configurez une clé SSH dans Settings → SSH Keys et transmettez son identifiant :

{
  "source": {
    "type": "git",
    "customGitUrl": "git@github.com:monorg/mondepot.git",
    "branch": "main",
    "buildPath": "/monsite",
    "buildType": "dockerfile",
    "customGitSSHKeyId": "ssh_xxx"
  }
}

Image Docker

Pour déployer une image déjà construite, sans étape de build :

{
  "source": {
    "type": "docker",
    "dockerImage": "monregistre/monapp:latest"
  }
}

Les variables d'environnement automatiques

Lorsqu'une base de données est comprise dans l'import, l'API renseigne d'elle-même les variables de connexion sur l'application :

Pour tous les types de base :

Variable	Valeur
`DB_HOST`	Le nom d'hôte du service Kubernetes interne
`DB_DATABASE`	Le nom de la base
`DB_USERNAME`	L'utilisateur de la base
`DB_PASSWORD`	Le mot de passe de la base

Variables supplémentaires, selon le type de base :

Base	Variable	Valeur
MySQL/MariaDB	`DB_PORT`	`3306`
MySQL/MariaDB	`DB_CONNECTION`	`mysql` ou `mariadb`
PostgreSQL	`DATABASE_URL`	`postgresql://utilisateur:motdepasse@hote:5432/base`
MongoDB	`MONGO_URL`	`mongodb://utilisateur:motdepasse@hote:27017/base`

Vos propres envVars sont appliquées ensuite : vous pouvez donc remplacer n'importe laquelle de ces valeurs générées.

Gestion des erreurs et reprise

Les statuts d'import

Statut	Signification
`pending`	L'import est en cours
`success`	Toutes les ressources ont été créées et le déploiement a été déclenché
`partial`	Certaines ressources ont été créées avant l'échec — relancez ou annulez
`failed`	Aucune ressource n'a été créée

Relancer un import en échec

Si un import échoue ou n'aboutit que partiellement, vous pouvez le relancer depuis la page Import Sites :

Repérez la carte de l'import en échec dans la liste Import History
Cliquez sur Retry — un indicateur tournant signale la reprise en cours
La carte se rafraîchit toutes les quelques secondes : vous voyez le statut passer de pending à success

La reprise est idempotente : elle met à jour l'enregistrement d'import existant au lieu d'en créer un double. Son déroulé :

elle nettoie les ressources partielles de la tentative précédente — elle supprime le projet, ce qui entraîne l'application, la base et le domaine ;
elle remet l'enregistrement d'import à pending ;
elle rejoue l'import complet à partir de la configuration enregistrée.

Vous pouvez relancer autant de fois que nécessaire : l'historique reste propre, avec un enregistrement par import.

Annuler un import partiel

Lorsqu'un import est partial — certaines ressources ont été créées — vous pouvez aussi choisir Rollback plutôt que de relancer. Cela supprime toutes les ressources créées et retire l'enregistrement d'import.

Relancer par l'API

# Via tRPC, depuis le tableau de bord ou par programme
siteImport.retry({ siteImportId: "abc123" })

Ce que « success » veut dire

Un statut success signifie que toutes les ressources — projet, base de données, application, domaine — ont été créées et que le déploiement a été déclenché. Mais la construction et le déploiement sont asynchrones : l'application peut encore être en cours de build, ou le déploiement échouer après la fin de l'import. Consultez les logs de déploiement dans Projects → [votre projet] → Application → Deployments pour en connaître l'état.

De même, si un domaine a été configuré en HTTPS, le certificat SSL (Let's Encrypt) est émis de façon asynchrone. Vérifiez que le DNS de votre domaine pointe bien vers l'adresse IP d'ingress de votre cluster pour que le certificat puisse être délivré.

Limites de l'offre

Les imports de site sont décomptés des quotas de votre offre — projets, applications, bases de données, domaines. En cas de dépassement, l'import échoue avec un message d'erreur qui indique clairement quel quota a été atteint.

Importer depuis le tableau de bord

Vous pouvez aussi importer des sites de façon visuelle, depuis la page Import Sites du tableau de bord Kuploy.

La marche à suivre

Ouvrez Import Sites dans la barre latérale (ou rendez-vous sur /import-sites)
Cliquez sur Import Site
Renseignez d'abord la source :
- Source Type — GitHub, GitLab, URL Git personnalisée ou image Docker
- Git Provider — choisissez votre fournisseur connecté (obligatoire pour GitHub et GitLab). Configurez-en un dans Settings → Git s'il n'y en a aucun.
- Repository — au format propriétaire/dépôt (par exemple monorg/virtualmin-sites)
- Build Path — le sous-répertoire contenant le Dockerfile (par exemple /monsite)
Cliquez sur « Auto-fill from site.json » — si le dépôt contient un fichier site.json à l'emplacement du chemin de build, les champs suivants se remplissent seuls :
- le nom du site, le domaine, le type, le nom et l'utilisateur de la base ;
- le chemin de build, déduit du nom du site ;
- si le dépôt n'est pas encore configuré, un sélecteur de fichier local s'ouvre à la place.
Complétez les champs restants :
- Domain (facultatif) — un domaine personnalisé, avec SSL automatique
- Branch — main par défaut
- Build Type — Dockerfile ou Nixpacks
- Port — le port de l'application (80 par défaut)
Si Include database est coché, renseignez :
- le type de base (MariaDB, MySQL, PostgreSQL, MongoDB) ;
- le nom, l'utilisateur et le mot de passe de la base — le mot de passe ne figure jamais dans site.json, saisissez-le à la main.
Ajoutez éventuellement des variables d'environnement (une par ligne, au format CLE=VALEUR)
Cliquez sur Preview pour valider : vous voyez ce qui sera créé et les éventuels avertissements
Cliquez sur Import Site pour créer l'ensemble

Une fois l'import terminé, le projet, l'application, la base de données et le domaine existent, et un déploiement est déclenché automatiquement. Si une base a été incluse, les variables de connexion (DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD) sont renseignées d'office sur l'application.

L'historique des imports

La page Import Sites liste tous les imports passés, avec leur statut :

Success — toutes les ressources créées, déploiement déclenché
Partial — certaines ressources créées avant un échec
Failed — aucune ressource créée, ou import annulé

Les imports en échec ou partiels se relancent depuis cette vue.

Exemple : migration depuis Virtualmin (en ligne de commande)

Une fois que l'administrateur de votre plateforme a lancé le script de migration, voir Migrer depuis Virtualmin — vous pouvez automatiser la suite :

#!/bin/bash
# Importer tous les sites depuis un dépôt virtualmin-sites

API_KEY="votre-cle-api"
KUPLOY_URL="https://console.example.com"
ORG_ID="org_xxx"
GITHUB_ID="gh_xxx"
REPO="monorg/virtualmin-sites"

for site_dir in /tmp/virtualmin-migrate/repo/*/; do
  site=$(basename "$site_dir")

  # Lire site.json
  domain=$(jq -r '.domain' "$site_dir/site.json")
  db_name=$(jq -r '.db_mysql' "$site_dir/site.json")
  db_user=$(jq -r '.mysql_user' "$site_dir/site.json")

  # Lire le mot de passe dans le fichier d'identifiants
  db_pass=$(grep "^$site " /tmp/virtualmin-migrate/credentials.txt | awk '{print $4}')

  echo "Import de $site ($domain)..."

  curl -s -X POST "$KUPLOY_URL/api/site-import" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"organizationId\": \"$ORG_ID\",
      \"name\": \"$site\",
      \"domain\": \"$domain\",
      \"database\": {
        \"type\": \"mariadb\",
        \"name\": \"$db_name\",
        \"user\": \"$db_user\",
        \"password\": \"$db_pass\"
      },
      \"source\": {
        \"type\": \"github\",
        \"repo\": \"$REPO\",
        \"branch\": \"main\",
        \"buildPath\": \"/$site\",
        \"buildType\": \"dockerfile\",
        \"githubId\": \"$GITHUB_ID\"
      },
      \"port\": 80
    }" | jq .

  echo ""
done

Après l'import, les sauvegardes de bases restent à charger à la main — voir importer le dump de la base : l'API crée le conteneur de base vide, mais l'import SQL demeure une opération extérieure.

Prérequis​

Démarrage rapide​

Authentification​

Les points d'accès​

POST /api/site-import — importer un site​

POST /api/site-import/preview — prévisualiser​

GET /api/site-import — lister les imports​

GET /api/site-import/:id — consulter un import​

Les types de source​

GitHub​

Git personnalisé (HTTPS ou SSH)​

Image Docker​

Les variables d'environnement automatiques​

Gestion des erreurs et reprise​

Les statuts d'import​

Relancer un import en échec​

Annuler un import partiel​

Relancer par l'API​

Ce que « success » veut dire​

Limites de l'offre​

Importer depuis le tableau de bord​

La marche à suivre​

L'historique des imports​

Exemple : migration depuis Virtualmin (en ligne de commande)​