Compose Stack Orchestration

The hubfly stack command family provides local-first orchestration for multi-container applications declared in standard docker-compose.yml files.

It parses Compose specifications, builds local services, streams image uploads, provisions managed persistent volumes, and deploys containers inside a single private project network.

Stack Orchestration Overview

Unlike conventional local Compose setups, hubfly stack translates local compose definitions directly onto Hubfly space platform infrastructure. State tracking is stored locally in .hubfly/stack.state.json inside your project directory.

Stack Subcommands & Options

Subcommand	Options & Flags	Description
`hubfly stack plan`	`--file <path>`, `--json`	Parses Compose manifest, resolves dependency graphs, and previews service/volume allocations without deploying.
`hubfly stack up`	`--file`, `--project`, `--region`, `--yes`, `--remove-orphans`, `--no-build`	Deploys stateful services in topological dependency order. Provisions named volumes and updates containers.
`hubfly stack status`	`--file <path>`	Queries Hubfly space API and displays runtime status for all containers tracked in stack state.
`hubfly stack logs`	`[service...]`, `--follow`, `-f`	Streams real-time combined stdout/stderr log output for specified or all stack services.
`hubfly stack exec`	`<service> -- <cmd> [args...]`	Executes a one-shot command inside target stack service container with 55s timeout.
`hubfly stack ssh`	`<service>`	Opens interactive PTY terminal session to specified stack container service.
`hubfly stack down`	`--file`, `--volumes`, `--yes`	Tears down stack services in reverse dependency order. Optionally deletes managed persistent volumes.

Docker Compose Translation Engine

The stack engine translates Compose spec directives to Hubfly space container parameters:

Compose Directive	Hubfly space Platform Translation	Notes & Constraints
`image: postgres:16-alpine`	Docker Image Source	Pulled directly by platform registry.
`build: ./backend`	Local Docker Build + Upload	Built on local machine via BuildKit, pushed to regional builder.
`volumes: [data:/var/lib/postgresql]`	Managed Volume Attachment	Named volumes auto-created on Hubfly space storage cluster.
`volumes: [./host:/app]`	Ignored with Warning	Local bind mounts are not supported on remote cloud instances; use named volumes.
`environment` / `env_file`	Container Env Variables	Loaded and injected into container process runtime environment.
`depends_on`	Deployment Topological Order	Services ordered so dependencies start before dependents.
`healthcheck`	Container Health Monitoring	Mapped to platform container health check probe.

DAG Dependency Cycle Resolution

Before executing hubfly stack up or hubfly stack plan, the CLI constructs a Directed Acyclic Graph (DAG) of all declared services.

If a circular dependency cycle is detected (e.g. Service A → Service B → Service A), the execution halts with an explicit cycle error before any resources are modified.

x-hubfly Compose Extensions

You can specify Hubfly space-native resource sizing directly inside your docker-compose.yml using the x-hubfly block:

version: "3.8"

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
    x-hubfly:
      tier: dedicated
      cpu: 2
      ram: 2048
      storage: 30
      autoSleep: false
      is24x7: true

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secretpassword
    volumes:
      - db-data:/var/lib/postgresql/data
    x-hubfly:
      tier: dedicated
      cpu: 1
      ram: 1024
      volumeSizeGb: 20

volumes:
  db-data:

Multi-Service Stack Examples

1. Previewing Stack Plan

terminal

$ hubfly stack plan --file docker-compose.yml

Hubfly space Stack Plan

ecommerce-app /home/developer/projects/ecommerce

Compose file: docker-compose.yml

Services: 2

Volumes: 1

- api -> ecommerce-app-api

source: local build

resources: 2.00 vCPU / 2048 MB RAM / 30 GB disk

ports: 8080/TCP

- db -> ecommerce-app-db

source: postgres:16-alpine

resources: 1.00 vCPU / 1024 MB RAM / 20 GB disk

volumes: 1 mount(s)

2. Deploying Stack to Cloud

terminal

$ hubfly stack up --project ecommerce-prod --region eu-west-1 --yes

Creating volume ecommerce-app_db-data

Service db

Recreating image-based service db

Service api

Deploy build id: bld_91f8a204

Local build: docker build for service api

Image upload: Streaming image to eu-west-1

Stack ecommerce-app is deployed in project ecommerce-prod (proj_77180)

3. Inspecting Logs and Shell Access

terminal

$ hubfly stack logs api -f

[api] Server listening on port 8080

[api] Connected to database host ecommerce-app-db:5432

$ hubfly stack exec db -- psql -U postgres -c '\l'

List of databases...

Orphan Cleanup

Pass --remove-orphans to hubfly stack up to clean up older platform containers when services are removed from your docker-compose.yml file.