mirror of
https://github.com/jhd3197/ServerKit.git
synced 2026-10-30 00:27:11 +09:00
Juan DenisandClaude Fable 5
284bc02dc1
A v1 manifest service gains a third image source next to buildpacks and
BYO image: — `dockerfilePath: services/api/Dockerfile`. This is the
monorepo path: one repository, several services, each built from its own
Dockerfile with the repo root as the shared build context.
- spec: new service key (camel + snake alias), validated relative-only
(no `..`/absolute), mutually exclusive with `image` and `containers`,
rejected on db services; schema docs copy kept in sync.
- resolve/plan: the path rides the create_app payload (with autoDeploy)
and shows in the step description; a changed path plans as an app
update; drift_pair tracks it against the stored build config.
- apply: create clones the project's repository into the managed apps
dir (idempotent — an existing checkout is reused) and writes the same
git-deployment + build config the import wizard does, so the existing
deploy pipeline (push webhook, per-service autoDeploy) takes over
unchanged. Source resolves from the stored manifest's provenance, else
a sibling app's git deployment; neither is a plan-time blocker
(dockerfile_no_source). Remote targets refuse like the other appliance
features ('a Dockerfile build' joins _service_features).
- scaffold: a dockerfile-built app round-trips its build config instead
of leaking the built image as a BYO `image:` declaration.
- import wizard: a v1 manifest with dockerfilePath seeds
build_method=dockerfile + the path.
Tests: 10 new (spec exclusivity/traversal + plan/apply/blocker wiring);
manifest suite 96/96, full backend suite green except 3 pre-existing
test_server_time_timezone failures also present on a clean tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
370 lines
14 KiB
JSON
370 lines
14 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://serverkit.ai/serverkit-yaml.schema.json",
|
|
"title": "ServerKit Manifest",
|
|
"description": "Declarative deployment manifest (serverkit.yaml / serverkit.json). A version:1 file describes a whole deployment — services, databases, disks, backups, env vars, cron and domains — that ServerKit parses, diffs against live state, and applies. camelCase is canonical; snake_case aliases are accepted everywhere.",
|
|
"type": "object",
|
|
"required": ["version"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"version": {
|
|
"description": "Manifest schema version. 1 selects the declarative multi-service spec. Files without version:1 are legacy flat manifests and keep their v0 behavior.",
|
|
"const": 1
|
|
},
|
|
"server": {
|
|
"description": "Optional default fleet target (agent server name or id). A service may override it. Omit for the local panel host.",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"project": {
|
|
"description": "Optional project name this manifest maps to. Defaults to the repository name.",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"envVars": {
|
|
"description": "Manifest-level (project-scoped) environment variables, applied to every service as a shared variable group.",
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/envVar" }
|
|
},
|
|
"services": {
|
|
"description": "The services that make up this deployment.",
|
|
"type": "array",
|
|
"minItems": 1,
|
|
"items": { "$ref": "#/definitions/service" }
|
|
},
|
|
"domains": {
|
|
"description": "Public domains routed to services.",
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/domain" }
|
|
}
|
|
},
|
|
"definitions": {
|
|
"service": {
|
|
"type": "object",
|
|
"required": ["name", "type"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"name": {
|
|
"description": "Unique service name within the manifest. Becomes the Application (or ManagedDatabase) name.",
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
|
|
"minLength": 1,
|
|
"maxLength": 63
|
|
},
|
|
"type": {
|
|
"description": "Service kind. web/worker/static/docker create Applications; postgres/mysql/mariadb/redis create ManagedDatabases.",
|
|
"enum": ["web", "worker", "static", "docker", "postgres", "mysql", "mariadb", "redis"]
|
|
},
|
|
"runtime": {
|
|
"description": "Build runtime hint for app services (e.g. python, node, static, docker). Ignored for db types.",
|
|
"type": "string"
|
|
},
|
|
"buildCommand": {
|
|
"description": "Command used to build the app (buildpack override).",
|
|
"type": "string"
|
|
},
|
|
"startCommand": {
|
|
"description": "Command used to start the app (buildpack override).",
|
|
"type": "string"
|
|
},
|
|
"dockerfilePath": {
|
|
"description": "Build the service from this Dockerfile in the repository (repo root = build context) — the monorepo path: one repo, several services, each built from its own Dockerfile. Relative path only; mutually exclusive with `image` and `containers`.",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"port": {
|
|
"description": "Container port the app listens on.",
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 65535
|
|
},
|
|
"ports": {
|
|
"description": "Typed L4 port publishes (appliance tier). Each entry is a raw tcp/udp publish — the escape hatch for services that speak more than HTTP (media/UDP, VoIP, brokers). The legacy scalar `port` keeps its HTTP/nginx behavior and is separate.",
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/portDecl" }
|
|
},
|
|
"image": {
|
|
"description": "Container image reference for a BYO-image app (appliance tier) — a first-class peer of the buildpack path.",
|
|
"type": "string"
|
|
},
|
|
"registry": {
|
|
"description": "Named private registry to authenticate against before pulling `image`. A registry that is unknown or has no stored credential is a plan-time blocker.",
|
|
"type": "string"
|
|
},
|
|
"hostRequirements": {
|
|
"description": "Elevated host requirements (appliance tier) — privileged/capAdd/sysctls/devices/kernelModules. Always listed in plain words in the plan; never applied silently.",
|
|
"$ref": "#/definitions/hostRequirements"
|
|
},
|
|
"bootstrap": {
|
|
"description": "First-boot bootstrap (appliance tier). Runs once via `docker compose run --rm` after volumes exist and before the first up — for appliances that generate a config tree once.",
|
|
"$ref": "#/definitions/bootstrap"
|
|
},
|
|
"containers": {
|
|
"description": "A multi-container UNIT (appliance tier): one service rendered as one compose project with a private network and health-gated dependsOn. Mutually exclusive with the buildpack keys. Keyed by container name.",
|
|
"type": "object",
|
|
"minProperties": 1,
|
|
"additionalProperties": { "$ref": "#/definitions/container" }
|
|
},
|
|
"healthCheckPath": {
|
|
"description": "HTTP path used for health checks and the zero-downtime restart gate.",
|
|
"type": "string"
|
|
},
|
|
"autoDeploy": {
|
|
"description": "When true, a push that changes this service's declared config auto-applies. Otherwise the manifest flips to pending and waits for an explicit apply.",
|
|
"type": "boolean",
|
|
"default": false
|
|
},
|
|
"version": {
|
|
"description": "Engine version for db services (e.g. \"16\" for postgres).",
|
|
"type": ["string", "number"]
|
|
},
|
|
"server": {
|
|
"description": "Per-service fleet target override.",
|
|
"type": "string"
|
|
},
|
|
"cpu": {
|
|
"description": "CPU limit (cores).",
|
|
"type": ["number", "string"]
|
|
},
|
|
"memory": {
|
|
"description": "Memory limit (e.g. 512MB, 1GB).",
|
|
"type": ["string", "number"]
|
|
},
|
|
"envVars": {
|
|
"description": "Per-service environment variables.",
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/envVar" }
|
|
},
|
|
"disks": {
|
|
"description": "Persistent volumes for app services.",
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/disk" }
|
|
},
|
|
"disk": {
|
|
"description": "Single primary disk for db services.",
|
|
"$ref": "#/definitions/disk"
|
|
},
|
|
"cron": {
|
|
"description": "Scheduled job(s) run in the service context.",
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/cron" },
|
|
{ "type": "array", "items": { "$ref": "#/definitions/cron" } }
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"bootstrap": {
|
|
"type": "object",
|
|
"required": ["command"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"command": {
|
|
"description": "Command run once inside a throwaway service container.",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"timeoutSeconds": {
|
|
"description": "Max seconds the bootstrap may run before it is killed and the step fails.",
|
|
"type": "integer",
|
|
"minimum": 1
|
|
}
|
|
}
|
|
},
|
|
"container": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"image": { "description": "Container image reference.", "type": "string" },
|
|
"registry": { "description": "Named private registry to authenticate against before pulling.", "type": "string" },
|
|
"ports": { "type": "array", "items": { "$ref": "#/definitions/portDecl" } },
|
|
"disks": { "type": "array", "items": { "$ref": "#/definitions/disk" } },
|
|
"envVars": { "type": "array", "items": { "$ref": "#/definitions/envVar" } },
|
|
"bootstrap": { "$ref": "#/definitions/bootstrap" },
|
|
"hostRequirements": { "$ref": "#/definitions/hostRequirements" },
|
|
"healthCheck": { "$ref": "#/definitions/healthCheck" },
|
|
"dependsOn": { "type": "array", "items": { "$ref": "#/definitions/dependsOn" } }
|
|
}
|
|
},
|
|
"healthCheck": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"cmd": { "description": "Shell command probe (rendered as CMD-SHELL).", "type": "string" },
|
|
"httpPath": { "description": "HTTP path probed with wget on localhost.", "type": "string" },
|
|
"interval": { "description": "e.g. 30s.", "type": "string" },
|
|
"timeout": { "description": "e.g. 5s.", "type": "string" },
|
|
"retries": { "type": "integer", "minimum": 1 }
|
|
}
|
|
},
|
|
"dependsOn": {
|
|
"type": "object",
|
|
"required": ["service"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"service": { "description": "Sibling container name in the same unit.", "type": "string" },
|
|
"condition": { "description": "healthy waits for the dependency's healthcheck; started only waits for it to start.", "enum": ["healthy", "started"] }
|
|
}
|
|
},
|
|
"hostRequirements": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"privileged": { "description": "Run privileged (big hammer — always shown in the plan, never silent).", "type": "boolean" },
|
|
"capAdd": { "description": "Linux capabilities to add.", "type": "array", "items": { "type": "string" } },
|
|
"sysctls": { "description": "sysctl key/value pairs.", "type": "object" },
|
|
"devices": { "description": "Host devices to expose.", "type": "array", "items": { "type": "string" } },
|
|
"kernelModules": { "description": "Kernel modules the workload needs (advisory /proc/modules check only).", "type": "array", "items": { "type": "string" } }
|
|
}
|
|
},
|
|
"portDecl": {
|
|
"type": "object",
|
|
"required": ["port"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"port": {
|
|
"description": "Host port to publish.",
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 65535
|
|
},
|
|
"containerPort": {
|
|
"description": "Container port to publish to. Defaults to the host port.",
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 65535
|
|
},
|
|
"protocol": {
|
|
"description": "L4 protocol. Defaults to tcp.",
|
|
"enum": ["tcp", "udp"]
|
|
},
|
|
"expose": {
|
|
"description": "public = bind 0.0.0.0 and open the firewall; local = bind 127.0.0.1 only. Defaults to public.",
|
|
"enum": ["public", "local"]
|
|
}
|
|
}
|
|
},
|
|
"envVar": {
|
|
"type": "object",
|
|
"required": ["key"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"key": {
|
|
"description": "Environment variable name.",
|
|
"type": "string",
|
|
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
},
|
|
"value": {
|
|
"description": "Literal value. Use only for non-secrets — secrets never live in the manifest.",
|
|
"type": ["string", "number", "boolean"]
|
|
},
|
|
"fromSecret": {
|
|
"description": "Reference to a vault secret by name; resolved at injection time, never stored in the env row.",
|
|
"type": "string"
|
|
},
|
|
"fromService": {
|
|
"description": "Reference to a sibling service's connection property.",
|
|
"type": "object",
|
|
"required": ["name", "property"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"name": { "type": "string" },
|
|
"property": {
|
|
"type": "string",
|
|
"enum": [
|
|
"connectionString", "host", "port", "database", "username", "password", "url"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"fromServer": {
|
|
"description": "Reference to the service's own target server identity (appliance tier). publicIp is what a NAT'd media/WebRTC bridge must advertise to clients.",
|
|
"type": "object",
|
|
"required": ["property"],
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"property": { "type": "string", "enum": ["publicIp", "hostname"] }
|
|
}
|
|
},
|
|
"generate": {
|
|
"description": "When true, ServerKit generates a random value on first apply, stores it as a vault secret, and rewires this entry as a fromSecret reference.",
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
},
|
|
"disk": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"name": {
|
|
"description": "Volume name.",
|
|
"type": "string"
|
|
},
|
|
"mountPath": {
|
|
"description": "Mount path inside the container.",
|
|
"type": "string"
|
|
},
|
|
"size": {
|
|
"description": "Requested size (e.g. 10GB). Recorded; not enforced by the local driver.",
|
|
"type": ["string", "number"]
|
|
},
|
|
"backup": { "$ref": "#/definitions/backup" }
|
|
}
|
|
},
|
|
"backup": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"schedule": {
|
|
"description": "Backup frequency.",
|
|
"type": "string",
|
|
"enum": ["hourly", "daily", "weekly", "monthly"]
|
|
},
|
|
"retain": {
|
|
"description": "Number of backups to keep.",
|
|
"type": "integer",
|
|
"minimum": 1
|
|
}
|
|
}
|
|
},
|
|
"cron": {
|
|
"type": "object",
|
|
"required": ["schedule", "command"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"name": { "type": "string" },
|
|
"schedule": {
|
|
"description": "Cron expression (5-field) or shorthand (daily, hourly...).",
|
|
"type": "string"
|
|
},
|
|
"command": {
|
|
"description": "Command to run.",
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"domain": {
|
|
"type": "object",
|
|
"required": ["host"],
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"host": {
|
|
"description": "Fully-qualified hostname (e.g. api.example.com).",
|
|
"type": "string",
|
|
"minLength": 1
|
|
},
|
|
"service": {
|
|
"description": "Name of the service this domain routes to.",
|
|
"type": "string"
|
|
},
|
|
"ssl": {
|
|
"description": "Certificate mode. auto = best-effort issuance (never blocks); off = HTTP only.",
|
|
"oneOf": [
|
|
{ "type": "string", "enum": ["auto", "off", "on"] },
|
|
{ "type": "boolean" }
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|