ComposeSpec v1.0 JSON Specification

Hubfly space Compose supports native JSON deployment stack definitions defined by the ComposeSpec v1.0 schema. This format allows programmatically declaring services, jobs, volumes, environment variables, resource limits, dependencies, and network aliases.

Schema Validation

All ComposeSpec JSON definitions submitted via the API, CLI, or visual editor are strictly validated using Zod against the composeSchema validator.

Top-Level Document Structure

Field	Type	Required	Description
`version`	`"1.0"`	No (Default: `"1.0"`)	Schema version identifier.
`name`	`string`	No	Name of the compose stack.
`description`	`string`	No	Human-readable description of the stack.
`volumes`	`VolumeSpec[]`	No	List of persistent volumes to provision for the stack.
`containers`	`ContainerSpec[]`	Yes (Min: 1)	Array of service and job containers in the stack.

Volume Specification (`VolumeSpec`)

Field	Type	Default	Description
`name`	`string`	Required	Unique volume identifier referenced in container mounts.
`sizeMB`	`number`	`100`	Storage capacity in megabytes (MB).
`driver`	`string`	`undefined`	Storage driver specification (e.g. `local`, `nvme`).
`labels`	`Record<string, string>`	`undefined`	Key-value metadata labels.

Container Specification (`ContainerSpec`)

Field	Type	Default	Description
`name`	`string`	Required	Service name within the stack.
`source`	`ComposeSource`	Required	Source specification (Docker image, Template, or Git build).
`kind`	`"service" \| "job"`	`"service"`	Workload type. `job` containers exit upon completion.
`tier`	`"shared" \| "dedicated" \| "auto-scale" \| "docker-os"`	`"shared"`	Hardware allocation tier.
`resources`	`ResourceSpec`	Tier Default	CPU, RAM, and Storage limits.
`runtime`	`RuntimeSpec`	Tier Default	Auto-sleep, auto-scale, and 24x7 runtime settings.
`dependsOn`	`(string \| DependencySpec)[]`	`[]`	Dependency conditions for execution ordering.
`env`	`EnvVarSpec[]`	`[]`	Environment variables list.
`ports`	`PortSpec[]`	`[]`	Container port mappings.
`mounts`	`MountSpec[]`	`[]`	Volume mounts.
`process`	`ProcessSpec`	`undefined`	Command, entrypoint, and working directory overrides.
`healthcheck`	`HealthcheckSpec`	`undefined`	Health check probe configuration.
`restartPolicy`	`RestartPolicySpec`	Kind Default	Container restart policy (`unless-stopped` for service, `no` for job).
`security`	`SecuritySpec`	`undefined`	Linux capability additions/drops.
`networkAliases`	`string[]`	`[]`	Private DNS network aliases.

Container Source Union Types (`ComposeSource`)

The source property is a discriminated union based on the type field:

1. Docker Image Source (`type: "docker"`)

{
  "type": "docker",
  "image": "postgres:16-alpine",
  "registryAuth": {
    "registry": "ghcr.io",
    "username": "acme-user",
    "password": "secret_token"
  }
}

2. Template Source (`type: "template"`)

{
  "type": "template",
  "templateId": "redis-standalone-v7"
}

3. Git Build Source (`type: "gitBuild"`)

{
  "type": "gitBuild",
  "repository": "acme/backend-api",
  "ref": "main",
  "context": ".",
  "dockerfile": "Dockerfile",
  "args": { "NODE_ENV": "production" }
}

Tier Hardware & Runtime Defaults

Tier	CPU (vCPU)	RAM (MB)	Storage (GB)	Runtime Behavior
`shared`	0.3	256	3	Locked to `autoSleep: true`, `is24x7: false`.
`dedicated`	1.0	512	5	Always-on (`is24x7: true`), optional auto-scaling.
`auto-scale`	1.0	512	5	Vertical/Horizontal auto-scaling enabled.
`docker-os`	2.0	2048	20	Full OS container workload.

Full Example ComposeSpec v1.0 Document

{
  "version": "1.0",
  "name": "Production App Stack",
  "description": "API with PostgreSQL database and migration job",
  "volumes": [
    {
      "name": "pg-data",
      "sizeMB": 5000
    }
  ],
  "containers": [
    {
      "name": "db",
      "source": {
        "type": "docker",
        "image": "postgres:16"
      },
      "tier": "dedicated",
      "resources": {
        "cpu": 1,
        "ram": 1024,
        "storage": 10
      },
      "env": [
        { "key": "POSTGRES_DB", "value": "app" },
        { "key": "POSTGRES_PASSWORD", "value": "secret", "secret": true }
      ],
      "mounts": [
        { "volume": "pg-data", "mountPath": "/var/lib/postgresql/data" }
      ],
      "healthcheck": {
        "test": ["CMD-SHELL", "pg_isready -U postgres"],
        "interval": "10s",
        "timeout": "5s",
        "retries": 5
      }
    },
    {
      "name": "migrate",
      "source": {
        "type": "gitBuild",
        "repository": "acme/api",
        "ref": "main",
        "context": ".",
        "dockerfile": "Dockerfile"
      },
      "kind": "job",
      "process": {
        "command": ["npm", "run", "db:migrate"]
      },
      "dependsOn": [
        { "service": "db", "condition": "service_healthy" }
      ]
    },
    {
      "name": "api",
      "source": {
        "type": "gitBuild",
        "repository": "acme/api",
        "ref": "main",
        "context": ".",
        "dockerfile": "Dockerfile"
      },
      "tier": "auto-scale",
      "ports": [
        { "container": 3000, "protocol": "HTTP" }
      ],
      "env": [
        { "key": "DATABASE_HOST", "value": "{{service:db.host}}" }
      ],
      "dependsOn": [
        { "service": "migrate", "condition": "service_completed_successfully" }
      ]
    }
  ]
}

ComposeSpec v1.0 JSON Specification

Top-Level Document Structure

Volume Specification (VolumeSpec)

Container Specification (ContainerSpec)

Container Source Union Types (ComposeSource)

1. Docker Image Source (type: "docker")

2. Template Source (type: "template")

3. Git Build Source (type: "gitBuild")