Format de l'architecture JSON
Structure complète du document d'architecture version 1.0 — blocs, champs, références entre blocs, transformations à l'export et dérivations à l'import.
This page has not been translated yet and is shown in French.
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 |
|---|---|---|---|
version | chaîne | oui | Toujours "1.0" |
kind | chaîne | oui | Toujours "wakastart-app-architecture" |
exportedAt | date-heure ISO 8601 | non | Posé à l'export, ignoré à l'import |
app | objet | oui | Nom et nom court de l'application d'origine, à titre indicatif |
repos | tableau | non | Dépôts Git |
harborProject | objet | non | Projet du registre d'images |
openbaoSecretEngine | objet | non | Coffre de secrets |
databaseDefinitions | tableau | non | Définitions de bases de données |
storageBucketDefinitions | tableau | non | Définitions de buckets |
serviceDefinitions | tableau | non | Définitions de service, avec leurs variables attendues |
appUrls | tableau | non | URLs publiques, sans domaine |
appRoutes | tableau | non | Routes HTTP entre une URL et un service |
appApexUrls | tableau | non | Expositions sur le domaine racine d'un domaine personnalisé |
appUrlRedirects | tableau | non | Redirections au niveau de l'application |
environments | tableau | 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 application |
Champs 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 |
|---|---|---|---|
name | chaîne | oui | 100 caractères au plus |
shortname | chaîne | oui | voir shortname |
L'import cible une application existante : ces valeurs ne la renomment pas.
repos[]
| Champ | Type | Obligatoire | Défaut | Description |
|---|---|---|---|---|
ref | ref | oui | Clé du dépôt dans le document | |
name | chaî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> | |
isManaged | booléen | non | true | true : Wakastart crée le dépôt ; false : référence à un dépôt existant |
fullName | chaîne | si isManaged: false | organisation/depot ; ignoré pour un dépôt géré | |
htmlUrl | URI ou null | si isManaged: false | URL HTTPS se terminant par .git ; ignorée pour un dépôt géré | |
defaultBranch | chaîne | non | main | 63 caractères au plus |
visibility | chaîne | non | internal | public, private ou internal |
harborProject et openbaoSecretEngine
| Bloc | Champ | Type | Défaut |
|---|---|---|---|
harborProject | importExisting | booléen | false |
harborProject | importExistingId | chaîne | |
openbaoSecretEngine | engineType | chaîne | kv-v2 |
openbaoSecretEngine | description | chaî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 |
|---|---|---|---|---|
ref | ref | oui | ||
name | chaîne | oui | 100 caractères au plus | |
shortname | shortname | oui | ||
engineType | chaîne | oui | POSTGRESQL, MYSQL, MONGODB, VALKEY | |
defaultMode | chaîne | non | IN_CLUSTER | IN_CLUSTER ou MANAGED |
defaultPlan | chaîne | non | 63 caractères au plus | |
defaultRegion | chaîne | non | 63 caractères au plus | |
defaultVersion | chaîne | non | 20 caractères au plus | |
defaultDiskSizeGb | entier | non | 1 au minimum | |
defaultStorageSize | chaîne | non | par exemple 10Gi | |
defaultReplicas | entier | non | 1 | 1 au minimum |
defaultDatabaseName | chaîne | non | 63 caractères au plus |
storageBucketDefinitions[]
| Champ | Type | Obligatoire | Défaut |
|---|---|---|---|
ref | ref | oui | |
name | chaîne, 100 caractères au plus | oui | |
shortname | shortname | oui | |
defaultRegion | chaîne | non | gra |
defaultStorageClass | chaîne | non | STANDARD |
defaultVersioning | booléen | non | false |
serviceDefinitions[]
| Champ | Type | Obligatoire | Défaut | Contraintes |
|---|---|---|---|---|
ref | ref | oui | ||
name | chaîne | oui | 100 caractères au plus | |
shortname | shortname | oui | ||
slug | chaîne | non | shortname | 63 caractères au plus |
repoRef | ref | oui | Dépôt du service | |
rootDirectory | chaîne | non | racine | Dossier du service dans le dépôt |
dockerfilePath | chaîne | non | Dockerfile | Relatif au contexte de build |
buildContext | chaîne | non | . | Relatif à rootDirectory |
imageRegistry | chaîne | non | registre de la plateforme | |
imageProject | chaîne | non | nom court de l'application cible | |
imageName | chaîne | oui | 63 caractères au plus | |
role | chaîne | oui | FRONT, BACK, BFF, WORKER | |
technology | chaîne | non | 50 caractères au plus ; nestjs, nextjs et custom fixent le port par défaut | |
defaultExposure | chaîne | oui | PUBLIC, INTERNAL, PRIVATE | |
defaultProtocol | chaîne | non | HTTP | |
defaultPort | entier | non | selon technology | 1 à 65535 |
defaultCpuRequest, defaultCpuLimit | chaîne | non | 100m, 500m | millicores, par exemple 250m |
defaultMemoryRequest, defaultMemoryLimit | chaîne | non | 128Mi, 512Mi | Mi ou Gi |
defaultHealthCheckPath | chaîne | non | /health | Chemin des sondes |
defaultHealthCheckInitialDelay | entier | non | 30 | Secondes avant la première sonde de vie |
defaultReadinessCheckPath, defaultStartupCheckPath | chaîne | non | chemin des sondes | |
defaultHealthCheckPort, defaultReadinessCheckPort, defaultStartupCheckPort | entier | non | 1 à 65535 | |
defaultLivenessProbeEnabled | booléen | non | true | |
defaultReadinessProbeEnabled | booléen | non | true | |
defaultStartupProbeEnabled | booléen | non | false | |
varRequirements | tableau | 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 |
|---|---|---|---|---|
envVarName | chaîne | oui | Nom de la variable, UPPER_SNAKE_CASE | |
required | booléen | non | true | |
description | chaîne | non | 500 caractères au plus | |
defaultValue | chaîne | non | Jamais un secret | |
mountType | chaîne | non | ENV_VAR | ENV_VAR ou FILE |
mountPath | chaîne | si FILE | Chemin absolu du fichier dans le conteneur | |
mountMode | chaîne | non | 0400 | Permissions octales |
mountSubPath | chaîne | non |
appUrls[] et appRoutes[]
| Bloc | Champ | Type | Obligatoire | Défaut |
|---|---|---|---|---|
appUrls | ref | ref | oui | |
appUrls | subdomain | chaîne, 63 caractères au plus | oui | |
appUrls | domainRef | toujours null | non | |
appRoutes | serviceRef | ref d'un service | oui | |
appRoutes | urlRef | ref d'une URL | oui | |
appRoutes | path | chaîne | non | / |
appRoutes | pathType | PathPrefix ou Exact | non | 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 |
|---|---|---|---|---|
appApexUrls | ref | ref | oui | |
appApexUrls | domainName | chaîne | oui | Nom du domaine personnalisé, par exemple mon-app.exemple.fr |
appApexUrls | serviceRef | ref d'un service | oui | Service qui reçoit le trafic |
appApexUrls | path, pathType | non | /, PathPrefix | |
appUrlRedirects | ref | ref | oui | |
appUrlRedirects | domainName | chaîne | oui | Domaine source |
appUrlRedirects | sourceSubdomain | chaîne ou null | non | null : la source est le domaine racine |
appUrlRedirects | targetUrlRef ou targetApexRef | ref | 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 |
|---|---|---|---|---|
env | chaîne | oui | dev, staging ou prod | |
shortname | shortname | oui | Sert aussi de nom de l'instance | |
slug | chaîne, 63 caractères au plus | oui | ||
gitRef | chaîne | non | valeur de env | Branche suivie, de type branche |
urlPrefix | chaî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.
Transformations à l'export
| 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[].slug | shortname |
serviceDefinitions[].imageProject | nom court de l'application cible |
serviceDefinitions[].imageRegistry | registre par défaut de la plateforme |
environments[].gitRef | valeur 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": "/" }
]
}