YAML spec reference

This page is the full reference for Minenet deployment YAML. If you want a guided explanation first, start with 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

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)

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

Get started

Platform

Deployments

Billing

CLI

Top-level schema

Resource union

Available regions and location IDs

Compute regions (`server.region`, `proxy-velocity.region`, `proxy-gate.region`)

Swiftbase locations (`swiftbase.location`)

YAML examples

Server resource

Server software env reference

Supported software types

Paper (`type: paper`)

Forge (`type: forge`)

NeoForge (`type: neoforge`)

Vanilla (`type: vanilla`)

Fabric (`type: fabric`)

CurseForge Modpack (`type: curseforge`)

Proxy Velocity resource

Proxy Gate resource

Swiftbase resource

Normalization rules (important)

Example (valid mixed deployment)

Common validation failures

Get started

Platform

Deployments

Billing

CLI

​Top-level schema

​Resource union

​Available regions and location IDs

​Compute regions (server.region, proxy-velocity.region, proxy-gate.region)

​Swiftbase locations (swiftbase.location)

​YAML examples

​Server resource

​Server software env reference

​Supported software types

​Paper (type: paper)

​Forge (type: forge)

​NeoForge (type: neoforge)

​Vanilla (type: vanilla)

​Fabric (type: fabric)

​CurseForge Modpack (type: curseforge)

​Proxy Velocity resource

​Proxy Gate resource

​Swiftbase resource

​Normalization rules (important)

​Example (valid mixed deployment)

​Common validation failures

​Related docs

Top-level schema

Resource union

Available regions and location IDs

Compute regions (`server.region`, `proxy-velocity.region`, `proxy-gate.region`)

Swiftbase locations (`swiftbase.location`)

YAML examples

Server resource

Server software env reference

Supported software types

Paper (`type: paper`)

Forge (`type: forge`)

NeoForge (`type: neoforge`)

Vanilla (`type: vanilla`)

Fabric (`type: fabric`)

CurseForge Modpack (`type: curseforge`)

Proxy Velocity resource

Proxy Gate resource

Swiftbase resource

Normalization rules (important)

Example (valid mixed deployment)

Common validation failures

Related docs