3. The model
Goal: Name the four core ideas from your first deploy and map each to a file or command.
Prerequisites: Chapter 2 — First deploy.
Four terms
| Term | One line | Your hello example |
|---|---|---|
| Bucket | One maand project directory | my-cluster/ where you ran maand init |
| Worker | A cluster node — SSH target | 10.0.0.1 in workspace/workers.json |
| Job | A deployable unit | hello under workspace/jobs/hello/ |
| Allocation | One job on one worker | hello @ 10.0.0.1 (created at build) |
Maand creates allocations automatically during maand build when a job's selectors match a worker's labels. Your hello job used "selectors": ["worker"]; every worker gets the worker label automatically.
Bucket vs worker
| Bucket (CLI host) | Worker | |
|---|---|---|
| You edit | workspace/, maand.conf |
Nothing in git — files arrive via deploy |
| Maand writes | data/maand.db, tmp/ |
/opt/maand/<bucket_id>/jobs/hello/ |
| Commands | maand build, maand deploy |
make start (called by deploy over SSH) |
The bucket is the source of truth for what should run. Workers hold runtime copies and data/ that persists across deploys.
Job lifecycle (simple view)
| Event | What maand does on the worker |
|---|---|
| First deploy to allocation | rsync files → make start |
| You change files and deploy again | rsync → make restart (default) |
| You remove job from workspace + build + deploy | stop + remove deployed files |
Your Makefile defines what start, stop, and restart mean.
Inspect allocations
maand cat allocations
maand cat allocations --jobs hello --workers 10.0.0.1
Columns disabled and removed matter later for drain and cleanup. Both 0 means active.
What you learned
- Bucket, worker, job, and allocation are the core model
- Build creates allocations by matching job selectors to worker labels
- Deploy rsyncs a job tree and runs Makefile targets on each allocation
Glossary: concepts. Deep detail: Reference: resources and placement.
Next
Chapter 4 — Project files: which paths you edit in git.