maand build

Build reads your workspace from disk, updates the bucket database (maand.db), fills the in-memory KV store (then persists it), and generates TLS material. It does not contact workers.

CLI

maand build [--purge-secrets-kv]

Prerequisites

1. maand init in the bucket directory (creates DB schema, default maand.conf, CA, SSH key, tmp/).
2. CGO_ENABLED=1 when compiling maand (SQLite driver).
3. Host tools for post_build hooks: python3, bun (if using Bun commands), bash, ssh, rsync.
4. Valid workspace/workers.json and at least one job under workspace/jobs/<name>/ with manifest.json and Makefile.

Workspace inputs

workspace/workers.json

Array of workers (hosts are SSH targets from the maand CLI host):

[
  {
    "host": "10.0.0.1",
    "labels": ["worker", "gpu"],
    "memory": "4096 mb",
    "cpu": "2000 mhz",
    "tags": { "zone": "a" }
  }
]

• host: Worker IP or hostname (required, unique).
• labels: Used for job selectors (label matching). The label worker is always added automatically.
• memory / cpu: Parsed to MB / MHz; stored on the worker row and exposed in KV. Set manually or probe with maand collect facts --generate-workers — collect.md.
• tags: Arbitrary key/value strings → namespace maand/worker/<ip>/tags/<key>.
• position: Ordering field (assigned from array index on read).

Optional fields are omitted from the file when unset (no null values).

Workers removed from workers.json are marked removed on allocations (not deleted until deploy/GC).

workspace/jobs/<job>/manifest.json

{
  "version": "1.0.0",
  "selectors": ["worker"],
  "max_concurrent_upgrades": 2,
  "max_concurrent_starts": 0,
  "resources": {
    "memory": { "min": "128 mb", "max": "512 mb" },
    "cpu": { "min": "100 mhz", "max": "500 mhz" },
    "ports": { "http_port": {} }
  },
  "hooks": {
    "hook_setup": {
      "executed_on": ["post_build", "pre_deploy"],
      "demands": {
        "job": "other_job",
        "hook": "hook_base",
        "config": {}
      }
    }
  },
  "certs": {
    "tls": {
      "pkcs8": false,
      "one": true,
      "subject": { "common_name": "app.example" }
    }
  }
}

Job version

Each job may declare version in manifest.json. Build stores it in job.version and KV (maand/job/<job>/version). When omitted, the target version is stored as 0.0.0.

Per-allocation target version (allocations.new_version) is set on maand build from manifest.json. Running version (hash.current_version) is updated on deploy promote — see deploy.md.

Format (validated when the field is present or required):

• Semver-like: major.minor.patch (missing segments default to 0, so "1" → 1.0.0)
• Optional leading v (v2.1.0)
• Optional prerelease suffix (2.0.0-rc1)
• Rejected: empty string, unknown, more than three numeric segments

When version is required

Version constraints on dependencies

In demands.config, optional bounds are checked against the upstream job’s version at build:

"demands": {
  "job": "database",
  "hook": "hook_schema",
  "config": {
    "min_version": "2.0.0",
    "max_version": "3.0.0"
  }
}

• min_version / max_version: string ("2.1.0") or integer (2 → 2.0.0)
• Build fails with ErrHookDemandVersionMismatch when upstream version is out of range

Full rules: manifest.md · deployment-sequence.md

Job directory rules

• Makefile or Makefile.tpl is required (default deploy uses runner.py → make start|stop|restart|reload per restart_policy; .tpl is rendered at deploy).
• Reserved directories on disk: data/, logs/, bin/ must not exist under the job folder (they are created on workers at runtime).
• Job files are copied into table job_files (content stored in DB).

Health check (build validation)

A job may define manifest probes, a health_check command, or both:

• health_check in manifest.json (built-in tcp/http/ssh probes), and/or
• A hook_* with executed_on: ["health_check"]

When both are defined, manifest probes run first at check time, then commands. Manifest probes are stored in job.health_check (JSON). Command-based health is stored in hooks like other events. See health-check.md.

workspace/disabled.json (optional)

How-to: disable-and-drain.md.

{
  "jobs": {
    "myjob": {
      "allocations": ["10.0.0.1"]
    }
  },
  "workers": ["10.0.0.2"]
}

• Disable entire job: "jobs": { "myjob": {} }.
• Disable specific workers for a job: "allocations": ["<worker_ip>", ...].
• Disable all jobs on a worker: "workers": ["<ip>", ...].

Disabled allocations are not active for deploy lifecycle (start/restart/reload/rsync) but still receive hook fan-out and deploy staging; rows remain until removed from workspace/build.

workspace/bucket.jobs.conf (optional)

Per-job reservations for memory and CPU in the current environment. Values must fall within manifest min/max (resources.memory / resources.cpu).

[myjob]
memory = "256 mb"
cpu = "500 mhz"

See configuration.md and resources-and-placement.md.

workspace/bucket.conf

Bucket-wide settings (TOML key/value). Created on maand init with a default port pool:

port_range = "30000,39999"

When port_range is omitted or empty in an existing file, build still uses 30000,39999.

Job manifests declare named ports in two ways:

• {} — maand assigns the lowest free port in the inclusive port_range pool at build time.
• An integer — you pin the port number in the manifest (any valid port; not limited to the bucket pool).

Assigned numbers are stored in ports and exposed in KV namespace maand/bucket (key <port_name>). Maand-provisioned ports keep the same number across rebuilds while it remains inside port_range. Changing a port from a fixed integer to {} reassigns from the pool when the stored number is outside that range (for example fixed 9500 → {} with default pool 30000,39999). Fixed ports always follow the manifest value.

"resources": {
  "ports": {
    "database_port": 5432,
    "http_port": {}
  }
}

Port names must be lowercase identifiers prefixed with <job>_ (for example api_http_port, echo_server_http) so keys stay distinct in the shared maand/bucket KV namespace. The same port number cannot be used by two jobs or two port names in the bucket.

Other keys in bucket.conf are copied to KV namespace vars/bucket.

maand.conf

Bucket-root SSH and cert settings. Full field reference: configuration.md.

What build does (order)

All steps run in one transaction (except post-build hooks), then VACUUM:

Deployment sequence (deployment_seq)

Derived from hooks.demand_job edges. See deployment-sequence.md for the full reference.

Summary:

• Jobs with no upstream demands → sequence 0.
• If job B’s command demands job A → B’s sequence is greater than A’s (max chain depth if multiple demands).
• Circular demands fail the build with ErrCircularHookDependency.
• All allocations for a job share the same deployment_seq.

Deploy runs sequences 0 .. max in order so depended-on jobs deploy first. post_build hooks use the same order.

Allocations

• One row per (worker_ip, job) match.
• alloc_id: Stable UUID from hash(job|workerIP).
• removed: Set when worker or job disappears from workspace (cleaned on deploy).
• disabled: From disabled.json or resource validation.

KV namespaces (build output)

Build populates catalog-backed namespaces (maand/*, vars/bucket/*, worker and job metadata, certs). Stable app config lives in vars/job/<job> and secrets/job/<job>.

Full namespace reference: KV namespaces. Persistence and purge: KV persistence.

Certificates

See certs.md for the full guide (CA, manifest options, auto-rotation, deploy paths). Summary:

• Bucket CA in secrets/ca.crt / ca.key (created on maand init; default TTL 10 years).
• Before BuildCerts, build runs checkCAExpiry: warning on stderr when the CA is expiring or PEM is invalid; build fails when the CA is expired. Same certs_renewal_buffer window as maand cat certs. The CA is not auto-renewed — replace secrets/ca.crt / ca.key manually.
• Per-job leaf certs from manifest → KV per allocation → jobs/<job>/certs/ on workers at deploy.
• Leaf certs regenerate when CA or manifest certs hash changes, or when within the certs_renewal_buffer window.
• Removing certs from the manifest purges certs/* KV keys on the next build.

post_build hooks

After the main commit, build runs every command registered with executed_on containing post_build, in deployment sequence order on non-removed allocations (includes disabled) on the CLI host (same runtime as deploy hooks).

• Uses hooks.Hook (same as deploy/CLI).
• Any hook failure fails maand build (main catalog commit already succeeded; fix hooks and re-run build).
• Useful for validation or codegen that must run before deploy.

Resource validation

If allocated jobs require memory or CPU (resources.memory / resources.cpu in the manifest), each worker hosting those jobs must declare memory / cpu in workers.json. Build fails when requirements exceed capacity or when a worker omits capacity while jobs require it.

When min_allocations_count is set on a job manifest, build fails with ErrInsufficientAllocations if label matching produces fewer non-removed allocations than the minimum.

Database tables touched

worker, worker_labels, worker_tags, job, job_selectors, hooks, job_files, ports, job_certs, allocations, hash, key_value, bucket, schema_version.

Inspect with:

maand cat workers
maand cat jobs
maand cat allocations
maand cat hooks
maand cat certs
maand cat kv

Common errors

When to run build

• After changing workers.json, jobs, disabled.json, or bucket.jobs.conf.
• Before maand deploy (or use maand deploy --build / -b).
• When you need cert rotation or catalog refresh before deploy.

Build does not start or restart processes on workers; that is deploy.

Related

• deploy.md — push artifacts and roll out
• hooks.md · hook-api.md
• KV namespaces · KV persistence
• templates.md — .tpl rendering
• configuration.md — maand.conf, bucket.conf
• health-check.md — health_check event