Learn maand
This track is for operators who already know Linux (SSH, users, systemd or Docker, Make) and may have used Ansible, Kubernetes, Nomad, or similar tools. It introduces maand one idea at a time, then links to reference pages for flags and schemas.
You do not need to read everything before your first deploy. Two paths:
| Path | Best if you… |
|---|---|
| Guided tour (chapters below) | Want to understand why before how |
| Hands-on first | Prefer typing commands → quickstart.md, then come back here |
After the tour, use concepts.md as a consolidated glossary and overview.md as a feature checklist.
Chapters
Read in order. Each chapter is short; skip ahead only if the topic is already familiar.
| # | Chapter | You will learn |
|---|---|---|
| 1 | Introduction | What maand is, what runs where, typical workflow |
| 2 | From your background | Map Linux / Ansible / K8s / Nomad ideas to maand |
| 3 | Bucket and workspace | maand init, directory layout, what you edit vs what maand generates |
| 4 | Workers | workers.json, SSH, labels, capacity, collect facts |
| 5 | Jobs and lifecycle | manifest.json, Makefile, start/stop/restart, compose/systemd |
| 6 | Allocations and placement | Job × worker matching, selectors, disable without delete |
| 7 | Build | Catalog, certs, validation — still no deploy to workers |
| 8 | Deploy | Rsync, rolling batches, restart vs reload, dry-run |
| 9 | Configuration, KV, and templates | Secrets, per-env CPU/memory, .tpl files |
| 10 | Hooks (hooks) | Python/Bun on the CLI host, runtime API, when to use hooks |
| 11 | Health and monitoring | Probes, Prometheus folder, pointers to logging docs |
| 12 | Day-2 operations | maand job, run_command, GC, drain, debugging |
Hands-on capstone: quickstart.md — init through first deploy.
Optional: comparison-orchestrators.md — deeper comparison to Kubernetes and Nomad.
Where to go next
| Goal | Document |
|---|---|
| Full CLI list | commands.md |
| Manifest fields | manifest.md |
| Rolling upgrades | rolling-deploy.md |
| Deploy failures | debugging-deploy.md |
| Maand command logs | logging.md |
| Hooks tutorial | hooks-tutorial.md |
| Doc index | README.md |