hubfly build and hubfly.build.json

The hubfly build commands let you inspect and control the build plan used byhubfly deploy. The config file is optional, but keeping it in your repository makes the selected source, commands, resources, ports and runtime behavior reviewable and repeatable.

What Build Commands Do

All four commands accept --config <path>. The value can be the path to a JSON file or a project directory; a directory resolves tohubfly.build.json inside it.

hubfly build init

Create a config for the current project, optionally selecting Dockerfile mode.

hubfly build validate

Validation loads or creates the config, applies defaults, resolves the build source, and checks the Dockerfile or the downloaded hubfly-builder. It does not deploy an image.

hubfly build edit

This command opens the normalized config in the editor named by EDITOR. For example:

hubfly build explain

Explain is the fastest way to answer “what will Hubfly space build from this directory?” In Dockerfile mode it prints the resolved Dockerfile. Otherwise it runs the builder inspection and reports the detected runtime, framework, version, working directory, context directory, exposed port, build arguments and the number of configured build secrets.

With --json, auto mode returns builderVersion and aninspect object. Dockerfile mode returns mode,dockerfile and config. Secret values are not printed.

hubfly.build.json Structure

The current schema version is 2. This is a complete representative file; omit optional properties you do not need. The CLI fills defaults for omitted values.

{
  "version": 2,
  "project": {
    "id": "proj_123",
    "name": "my-api",
    "region": "rw-kigali-1"
  },
  "container": {
    "id": "cnt_123",
    "name": "my-api"
  },
  "build": {
    "mode": "auto",
    "dockerfilePath": "deploy/Dockerfile",
    "workingDir": ".",
    "contextDir": ".",
    "runtime": "node",
    "framework": "next",
    "version": "22",
    "installCommand": "npm ci",
    "setupCommands": ["npm run db:generate"],
    "buildCommand": "npm run build",
    "postBuildCommands": [],
    "runCommand": "npm run start",
    "runtimeInitCommand": "",
    "exposePort": "3000"
  },
  "deploy": {
    "tier": "dedicated",
    "resources": { "cpu": 1, "ram": 800, "storage": 1 },
    "runtime": { "autoSleep": false, "autoScale": false, "is24x7": true },
    "networkPrimaryAlias": "api",
    "networkAliases": ["backend"],
    "ports": [
      { "container": 3000, "protocol": "HTTP" }
    ],
    "volumes": [
      { "name": "postgres-data", "mountPath": "/var/lib/postgresql/data" }
    ],
    "process": {
      "command": ["npm", "run", "start"],
      "entrypoint": [],
      "workingDir": "/app"
    },
    "healthcheck": {
      "test": ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"],
      "interval": "30s",
      "timeout": "5s",
      "startPeriod": "20s",
      "retries": 3
    },
    "restartPolicy": { "name": "unless-stopped" },
    "labels": { "app": "my-api" }
  },
  "env": [
    { "name": "NODE_ENV", "value": "production", "scope": "runtime" },
    { "name": "NPM_TOKEN", "value": "secret", "secret": true, "scope": "build" }
  ],
  "remove": {
    "environmentKeys": [],
    "portIds": [],
    "volumeIds": []
  },
  "metadata": {
    "builderVersion": "v1.7.1",
    "lastBuildId": "build_123",
    "lastImageTag": "build_123-20260819T120000Z",
    "lastImageDisplay": "registry.example/my-api:build_123",
    "lastDeployedAt": "2026-08-19T12:00:00Z"
  }
}

Build Fields

Deploy Fields

Environment and Metadata

Each env entry has name, value, optionalsecret, optional scope, and optional from. Scope isruntime by default; use build for build-only values orboth when the same value is needed in both phases. Mark credentials assecret: true and do not print them in CI logs.

project.id, container.id, and the metadata fields are normally maintained by the CLI after a successful binding or deploy. Review them, but avoid hand-editing generated IDs and image metadata. The remove lists are used by the deploy diff when you intentionally remove existing environment keys, ports or volume mounts.

Recommended Workflow

1. Run init once and inspect the generated defaults.
2. Use explain to verify detection before changing commands manually.
3. Commit the config when you want reviewable, repeatable deploy behavior.
4. Run validate --json in CI as a preflight check.
5. Use hubfly deploy --yes only after reviewing the deploy diff; add --detach when the job should return after upload.