> ## Documentation Index > Fetch the complete documentation index at: https://docs.minenet.pro/llms.txt > Use this file to discover all available pages before exploring further. # YAML spec reference > Complete reference for the deployment YAML schema, resource types, defaults, and validation rules. This page is the full reference for Minenet deployment YAML. If you want a guided explanation first, start with [Configurations and YAML](/guides/deployments/configurations-and-yaml). ## Top-level schema | Field | Type | Required | Rules | | ---------------- | ------ | -------- | ------------------------------ | | `apiVersion` | string | Yes | Must be `minenet.pro/v1alpha1` | | `kind` | string | Yes | Must be `Deployment` | | `metadata.name` | string | No | 1-64 chars (if provided) | | `spec.resources` | array | Yes | Max 32 resources | Additional constraints: * YAML payload max size: `64 KB` * `spec.resources: null` is normalized to `[]` * Resource IDs must be unique (case-insensitive) ## Resource union Each item in `spec.resources` must be one of: * `type: server` * `type: proxy-velocity` * `type: proxy-gate` * `type: swiftbase` All resource types require: | Field | Type | Required | Rules | | ------ | ------ | -------- | ------------------------------------------------------------ | | `id` | string | Yes | 1-64 chars | | `type` | string | Yes | One of `server`, `proxy-velocity`, `proxy-gate`, `swiftbase` | | `name` | string | Yes | Resource-type-specific max length | ## Available regions and location IDs Use these IDs in deployment YAML. ### Compute regions (`server.region`, `proxy-velocity.region`, `proxy-gate.region`) | ID | Region name | Notes | | -------- | ------------- | ---------- | | `ams` | Amsterdam, NL | Production | | `dallas` | Dallas, TX | Production | ### Swiftbase locations (`swiftbase.location`) | ID | Location | Region | | ------ | ------------- | ------ | | `nbg1` | Nuremberg, DE | EU | | `hel1` | Helsinki, FI | EU | | `ash` | Ashburn, US | US | | `hil` | Hillsboro, US | US | ### YAML examples ```yaml theme={null} spec: resources: - id: web-server type: server name: Web Server region: dallas resources: memoryGb: 8 storageGb: 40 software: install: type: paper minecraftVersion: latest - id: edge-velocity type: proxy-velocity name: Edge Velocity region: ams resources: memoryGb: 2 storageGb: 10 velocity: version: latest - id: edge-gate type: proxy-gate name: Edge Gate region: dallas resources: memoryGb: 1 storageGb: 10 managed: enabled: true rules: - namePattern: "lobby-*" exclude: ["lobby-test*"] - id: app-db type: swiftbase name: app-db location: nbg1 serverType: cpx22 ``` ## Server resource Required shape: | Field | Type | Required | Rules | | ----------------------------------- | ------------- | -------- | ----------------------------------------------------- | | `id` | string | Yes | 1-64 chars | | `type` | string | Yes | Must be `server` | | `name` | string | Yes | 1-64 chars | | `region` | string | Yes | Non-empty | | `resources.memoryGb` | integer | Yes | Min 4, max 16 | | `resources.storageGb` | integer | No | Min 10, max 200, default 10 | | `software.install.type` | string | Yes | Non-empty | | `software.install.minecraftVersion` | string | Yes | Non-empty | | `software.install.java` | string/number | No | One of `auto`, `8`, `16`, `17`, `21` (default `auto`) | | `software.install.env` | object | No | Key-value map of string/number/boolean | | `software.restore` | object | No | See restore fields below | Optional restore block: | Field | Type | Required | Rules | | ------------------------------------ | ------- | ------------------------- | -------------- | | `software.restore.snapshotUuid` | string | Yes (if restore provided) | Must be UUID | | `software.restore.truncateDirectory` | boolean | No | Default `true` | ## Server software env reference Use this section when setting `software.install.type` and `software.install.env`. ### Supported software types | `software.install.type` | Software | | ----------------------- | ------------------ | | `paper` | Paper | | `forge` | Forge | | `neoforge` | NeoForge | | `vanilla` | Vanilla | | `fabric` | Fabric | | `curseforge` | CurseForge Modpack | `GET /api/client/v1/servers/software` returns the current catalog for server software profiles. General rules for `software.install.env`: * Keys are case-sensitive. * Values can be `string`, `number`, or `boolean`. * Unknown keys are rejected. * For version keys (`MINECRAFT_VERSION`, `MC_VERSION`, `VANILLA_VERSION`), set `software.install.minecraftVersion` instead of overriding in `env`. ### Paper (`type: paper`) | Variable | Required | Default | How to set | | ------------------- | -------- | -------- | ------------------------------------------ | | `MINECRAFT_VERSION` | Yes | `latest` | Use `software.install.minecraftVersion` | | `BUILD_NUMBER` | No | `latest` | Set in `software.install.env.BUILD_NUMBER` | ### Forge (`type: forge`) | Variable | Required | Default | How to set | | ------------ | -------- | ------------- | ---------------------------------------- | | `MC_VERSION` | Yes | `latest` | Use `software.install.minecraftVersion` | | `BUILD_TYPE` | No | `recommended` | Set in `software.install.env.BUILD_TYPE` | ### NeoForge (`type: neoforge`) | Variable | Required | Default | How to set | | ------------------ | -------- | -------- | ---------------------------------------------- | | `MC_VERSION` | Yes | `latest` | Use `software.install.minecraftVersion` | | `NEOFORGE_VERSION` | Yes | none | Set in `software.install.env.NEOFORGE_VERSION` | ### Vanilla (`type: vanilla`) | Variable | Required | Default | How to set | | ----------------- | -------- | -------- | --------------------------------------- | | `VANILLA_VERSION` | Yes | `latest` | Use `software.install.minecraftVersion` | ### Fabric (`type: fabric`) | Variable | Required | Default | How to set | | ---------------- | -------- | -------- | -------------------------------------------- | | `MC_VERSION` | Yes | `latest` | Use `software.install.minecraftVersion` | | `FABRIC_VERSION` | No | `latest` | Set in `software.install.env.FABRIC_VERSION` | | `LOADER_VERSION` | No | `latest` | Set in `software.install.env.LOADER_VERSION` | ### CurseForge Modpack (`type: curseforge`) | Variable | Required | Default | How to set | | ------------ | -------- | ------- | ---------------------------------------- | | `PROJECT_ID` | Yes | none | Set in `software.install.env.PROJECT_ID` | | `VERSION_ID` | Yes | none | Set in `software.install.env.VERSION_ID` | ## Proxy Velocity resource Required shape: | Field | Type | Required | Rules | | ---------------------- | ------- | -------- | ------------------------ | | `id` | string | Yes | 1-64 chars | | `type` | string | Yes | Must be `proxy-velocity` | | `name` | string | Yes | 1-64 chars | | `region` | string | Yes | Non-empty | | `resources.memoryGb` | integer | Yes | Min 1, max 4 | | `resources.storageGb` | integer | No | Must be 10, default 10 | | `velocity.version` | string | No | Non-empty when present | | `velocity.buildNumber` | string | No | Non-empty when present | ## Proxy Gate resource Required shape: | Field | Type | Required | Rules | | --------------------- | ------- | -------- | ---------------------- | | `id` | string | Yes | 1-64 chars | | `type` | string | Yes | Must be `proxy-gate` | | `name` | string | Yes | 1-64 chars | | `region` | string | Yes | Non-empty | | `resources.memoryGb` | integer | Yes | Min 1, max 4 | | `resources.storageGb` | integer | No | Must be 10, default 10 | | `managed.enabled` | boolean | No | Default `false` | | `managed.rules` | array | No | Max 64 entries | `managed.rules` requirements: * each rule must contain exactly one of `serverId` or `namePattern` * `serverId` must be a UUID when present * `namePattern` max length is 128 * `exclude` supports up to 32 patterns per rule ## Swiftbase resource Required shape: | Field | Type | Required | Rules | | ------------ | ------ | -------- | ------------------------------------------------- | | `id` | string | Yes | 1-64 chars | | `type` | string | Yes | Must be `swiftbase` | | `name` | string | Yes | 1-63 chars | | `location` | string | Yes | One of `nbg1`, `hel1`, `ash`, `hil` | | `serverType` | string | No | Must be valid and available for selected location | If `serverType` is omitted, Minenet applies a location default during normalization. ## Normalization rules (important) Before reconciliation, Minenet normalizes input: * Resource IDs are sanitized to lowercase slug-like format. * Name fields are sanitized (control characters removed, whitespace normalized). * Server/proxy resource values are clamped to allowed bounds. * Swiftbase `location`/`serverType` are normalized to lowercase. * Known software names are canonicalized (for example, `CurseForge Modpack` -> `curseforge`). ## Example (valid mixed deployment) ```yaml theme={null} apiVersion: minenet.pro/v1alpha1 kind: Deployment metadata: name: production spec: resources: - id: main-server type: server name: Main Server region: dallas resources: memoryGb: 8 storageGb: 40 software: install: type: paper minecraftVersion: latest java: auto - id: edge-velocity type: proxy-velocity name: Edge Velocity region: dallas resources: memoryGb: 2 storageGb: 10 velocity: version: latest - id: edge-gate type: proxy-gate name: Edge Gate region: dallas resources: memoryGb: 1 storageGb: 10 managed: enabled: true rules: - serverId: "550e8400-e29b-41d4-a716-446655440000" - id: main-db type: swiftbase name: main-db location: ash serverType: cpx21 ``` ## Common validation failures * Wrong `apiVersion` or `kind` * Duplicate resource IDs * Too many resources (>32) * Invalid proxy type (`proxy` instead of `proxy-velocity`/`proxy-gate`) * Invalid Swiftbase location/serverType combination * Out-of-range memory/storage values * Invalid restore snapshot UUID ## Related docs * [Configurations and YAML](/guides/deployments/configurations-and-yaml) * [Run lifecycle and monitoring](/guides/deployments/run-lifecycle-and-monitoring) * [Safe rollouts and troubleshooting](/guides/deployments/safe-rollouts-and-troubleshooting)