Le document d'architecture décrit les définitions d'une application, sans identifiant ni valeur propre à une application donnée. La console le produit avec Exporter et l'accepte avec Importer ; voir Exporter et importer l'architecture .
Le format est validé par un schéma JSON (draft 2020-12). Tout champ non décrit ici est refusé.
Racine du document#
Champ Type Obligatoire Description versionchaîne oui Toujours "1.0" kindchaîne oui Toujours "wakastart-app-architecture" exportedAtdate-heure ISO 8601 non Posé à l'export, ignoré à l'import appobjet oui Nom et nom court de l'application d'origine, à titre indicatif repostableau non Dépôts Git harborProjectobjet non Projet du registre d'images openbaoSecretEngineobjet non Coffre de secrets databaseDefinitionstableau non Définitions de bases de données storageBucketDefinitionstableau non Définitions de buckets serviceDefinitionstableau non Définitions de service, avec leurs variables attendues appUrlstableau non URLs publiques, sans domaine appRoutestableau non Routes HTTP entre une URL et un service appApexUrlstableau non Expositions sur le domaine racine d'un domaine personnalisé appUrlRedirectstableau non Redirections au niveau de l'application environmentstableau non Environnements à créer, sans instance
Références entre blocs#
Les blocs se désignent par leur clé ref, jamais par un identifiant de la plateforme.
Règle Valeur Format d'une ref ^[a-z0-9][a-z0-9-]{0,62}$Format d'un shortname ^[a-z0-9][a-z0-9-]{0,11}$, unique par applicationChamps qui pointent vers une ref repoRef, serviceRef, urlRef, targetUrlRef, targetApexRef
La validation vérifie que chaque référence pointe vers un bloc existant (message Unknown repo ref "…", Unknown serviceDefinition ref "…", Unknown appUrl ref "…", Unknown appApexUrl ref "…").
app#
Champ Type Obligatoire Contraintes namechaîne oui 100 caractères au plus shortnamechaîne oui voir shortname
L'import cible une application existante : ces valeurs ne la renomment pas.
repos[]#
Champ Type Obligatoire Défaut Description refref oui Clé du dépôt dans le document namechaîne oui ^[a-z0-9][a-z0-9-]*$, 63 caractères au plus ; sur GitHub, un dépôt géré est nommé <wid>-<name>isManagedbooléen non truetrue : Wakastart crée le dépôt ; false : référence à un dépôt existantfullNamechaîne si isManaged: false organisation/depot ; ignoré pour un dépôt géréhtmlUrlURI ou null si isManaged: false URL HTTPS se terminant par .git ; ignorée pour un dépôt géré defaultBranchchaîne non main63 caractères au plus visibilitychaîne non internalpublic, private ou internal
harborProject et openbaoSecretEngine#
Bloc Champ Type Défaut harborProjectimportExistingbooléen falseharborProjectimportExistingIdchaîne openbaoSecretEngineengineTypechaîne kv-v2openbaoSecretEnginedescriptionchaîne, 500 caractères au plus
Le nom du projet et le chemin du coffre sont recalculés pour l'application cible.
databaseDefinitions[]#
Champ Type Obligatoire Défaut Contraintes refref oui namechaîne oui 100 caractères au plus shortnameshortname oui engineTypechaîne oui POSTGRESQL, MYSQL, MONGODB, VALKEYdefaultModechaîne non IN_CLUSTERIN_CLUSTER ou MANAGEDdefaultPlanchaîne non 63 caractères au plus defaultRegionchaîne non 63 caractères au plus defaultVersionchaîne non 20 caractères au plus defaultDiskSizeGbentier non 1 au minimum defaultStorageSizechaîne non par exemple 10Gi defaultReplicasentier non 11 au minimum defaultDatabaseNamechaîne non 63 caractères au plus
storageBucketDefinitions[]#
Champ Type Obligatoire Défaut refref oui namechaîne, 100 caractères au plus oui shortnameshortname oui defaultRegionchaîne non gradefaultStorageClasschaîne non STANDARDdefaultVersioningbooléen non false
serviceDefinitions[]#
Champ Type Obligatoire Défaut Contraintes refref oui namechaîne oui 100 caractères au plus shortnameshortname oui slugchaîne non shortname63 caractères au plus repoRefref oui Dépôt du service rootDirectorychaîne non racine Dossier du service dans le dépôt dockerfilePathchaîne non DockerfileRelatif au contexte de build buildContextchaîne non .Relatif à rootDirectory imageRegistrychaîne non registre de la plateforme imageProjectchaîne non nom court de l'application cible imageNamechaîne oui 63 caractères au plus rolechaîne oui FRONT, BACK, BFF, WORKERtechnologychaîne non 50 caractères au plus ; nestjs, nextjs et custom fixent le port par défaut defaultExposurechaîne oui PUBLIC, INTERNAL, PRIVATEdefaultProtocolchaîne non HTTPdefaultPortentier non selon technology 1 à 65535 defaultCpuRequest, defaultCpuLimitchaîne non 100m, 500mmillicores, par exemple 250m defaultMemoryRequest, defaultMemoryLimitchaîne non 128Mi, 512MiMi ou GidefaultHealthCheckPathchaîne non /healthChemin des sondes defaultHealthCheckInitialDelayentier non 30Secondes avant la première sonde de vie defaultReadinessCheckPath, defaultStartupCheckPathchaîne non chemin des sondes defaultHealthCheckPort, defaultReadinessCheckPort, defaultStartupCheckPortentier non 1 à 65535 defaultLivenessProbeEnabledbooléen non truedefaultReadinessProbeEnabledbooléen non truedefaultStartupProbeEnabledbooléen non falsevarRequirementstableau non Variables attendues
Important
Renseignez les ressources dans le format accepté par la console : CPU en millicores (250m), mémoire en Mi ou Gi (512Mi, 1Gi), avec au plus 2000m de CPU et 8Gi de mémoire. Une valeur hors de ce format empêche ensuite de modifier le service depuis la console.
varRequirements[]#
Champ Type Obligatoire Défaut Description envVarNamechaîne oui Nom de la variable, UPPER_SNAKE_CASE requiredbooléen non truedescriptionchaîne non 500 caractères au plus defaultValuechaîne non Jamais un secret mountTypechaîne non ENV_VARENV_VAR ou FILEmountPathchaîne si FILE Chemin absolu du fichier dans le conteneur mountModechaîne non 0400Permissions octales mountSubPathchaîne non
appUrls[] et appRoutes[]#
Bloc Champ Type Obligatoire Défaut appUrlsrefref oui appUrlssubdomainchaîne, 63 caractères au plus oui appUrlsdomainReftoujours null non appRoutesserviceRefref d'un service oui appRoutesurlRefref d'une URL oui appRoutespathchaîne non /appRoutespathTypePathPrefix ou Exactnon PathPrefix
À l'import, les URLs sont rattachées au domaine de la plateforme s'il existe, sinon créées détachées : rattachez-les ensuite depuis Architecture > URLs .
appApexUrls[] et appUrlRedirects[]#
Bloc Champ Type Obligatoire Description appApexUrlsrefref oui appApexUrlsdomainNamechaîne oui Nom du domaine personnalisé, par exemple mon-app.exemple.fr appApexUrlsserviceRefref d'un service oui Service qui reçoit le trafic appApexUrlspath, pathTypenon /, PathPrefixappUrlRedirectsrefref oui appUrlRedirectsdomainNamechaîne oui Domaine source appUrlRedirectssourceSubdomainchaîne ou null non null : la source est le domaine racineappUrlRedirectstargetUrlRef ou targetApexRefref un des deux Exactement une cible
Ces deux blocs ne s'importent que si l'application cible possède déjà un domaine personnalisé du même nom ; sinon l'entrée est ignorée sans bloquer l'import.
environments[]#
Champ Type Obligatoire Défaut Description envchaîne oui dev, staging ou prodshortnameshortname oui Sert aussi de nom de l'instance slugchaîne, 63 caractères au plus oui gitRefchaîne non valeur de env Branche suivie, de type branche urlPrefixchaîne, 20 caractères au plus non aucun Préfixe d'URL
Un environnement n'est pas créé si l'application cible possède déjà un environnement du même type. Aucune instance n'est créée.
Transformation Effet Champs propres à l'application Identifiant, chemins et noms qui en dérivent, champs d'état retirés Dépôts gérés Exportés avec "isManaged": false et leur URL .git ; l'export échoue si un dépôt géré n'a pas encore d'URL URLs Détachées de leur domaine (domainRef: null) Domaines personnalisés Non exportés ; seuls leurs noms subsistent dans appApexUrls et appUrlRedirects Exigences de secrets, nombre de versions conservées du coffre Non exportés
Dérivations à l'import#
Champ absent Valeur appliquée serviceDefinitions[].slugshortnameserviceDefinitions[].imageProjectnom court de l'application cible serviceDefinitions[].imageRegistryregistre par défaut de la plateforme environments[].gitRefvaleur de env
L'import est transactionnel : soit tout est créé, soit rien. Ordre de création : dépôts, projet du registre, coffre, bases, buckets, services et variables, URLs, domaines racines, routes, redirections, environnements.
Exemple complet#
{
"version" : "1.0" ,
"kind" : "wakastart-app-architecture" ,
"app" : { "name" : "Mon app exemple" , "shortname" : "monapp" } ,
"repos" : [
{
"ref" : "monorepo" ,
"name" : "wk-monapp" ,
"isManaged" : false ,
"fullName" : "exemple-org/wk-monapp" ,
"htmlUrl" : "https://github.com/exemple-org/wk-monapp.git" ,
"defaultBranch" : "main"
}
] ,
"databaseDefinitions" : [
{ "ref" : "main-db" , "name" : "Base principale" , "shortname" : "main" , "engineType" : "POSTGRESQL" , "defaultMode" : "MANAGED" , "defaultVersion" : "16" }
] ,
"serviceDefinitions" : [
{
"ref" : "api" ,
"name" : "API" ,
"shortname" : "api" ,
"repoRef" : "monorepo" ,
"rootDirectory" : "services/api" ,
"imageName" : "api" ,
"role" : "BACK" ,
"technology" : "nestjs" ,
"defaultExposure" : "INTERNAL" ,
"defaultPort" : 3000 ,
"defaultMemoryLimit" : "1Gi" ,
"varRequirements" : [
{ "envVarName" : "LOG_LEVEL" , "defaultValue" : "info" , "required" : false } ,
{ "envVarName" : "DATABASE_URL" }
]
} ,
{
"ref" : "front" ,
"name" : "Front" ,
"shortname" : "front" ,
"repoRef" : "monorepo" ,
"rootDirectory" : "apps/front" ,
"imageName" : "front" ,
"role" : "FRONT" ,
"technology" : "nextjs" ,
"defaultExposure" : "PUBLIC"
}
] ,
"appUrls" : [
{ "ref" : "app" , "subdomain" : "app" } ,
{ "ref" : "api" , "subdomain" : "api" }
] ,
"appRoutes" : [
{ "serviceRef" : "front" , "urlRef" : "app" , "path" : "/" } ,
{ "serviceRef" : "api" , "urlRef" : "api" , "path" : "/" }
]
}