Operator manual
Run a Yggdrasil node, end-to-end.
Fourteen chapters that walk an operator from a fresh machine to a long-running production deployment. Start at the top if you're new; use the cards below to jump straight to what you need.
Get a node running
- → 1. Overview What a Cardano node does and where Yggdrasil fits.
- → 2. Installation Prerequisites and a clean build from source.
- → 3. From releases Pre-built Linux binaries with SHA256 verification.
- → 4. Quick Start Sync mainnet in five commands.
Configure for your network
- → 5. Networks & presets Mainnet, preprod, preview — when and why each.
- → 6. Configuration Every config key, CLI flag, and topology option.
- → 7. Running a node Daemonising, signal handling, graceful shutdown.
-
→
8. Docker
Containerised deployment with
docker compose.
Operate over time
- → 9. Monitoring Prometheus, structured traces, dashboards, alerts.
- → 10. Block production KES, VRF, OpCert — stake pool credentials.
-
→
11. CLI reference
Every
yggdrasil-nodesubcommand and flag. - → 12. Maintenance Backups, KES rotation, upgrades, log rotation.
- → 13. Troubleshooting Common errors and the resolutions that work.
- → 14. Glossary Cardano terminology, defined.
Conventions
- Commands prefixed with
$are run as a non-root user. - Commands prefixed with
#are run as root. - Paths in
<angle brackets>are placeholders you replace with your actual paths. - Code blocks without a prompt are file contents.
- “Upstream” refers to the Haskell
cardano-nodefrom IntersectMBO, which Yggdrasil targets for parity.
Operating-system support
| OS | Build | Run | Notes |
|---|---|---|---|
| Linux x86_64 | ✓ | ✓ | Primary supported platform |
| Linux aarch64 | ✓ | ✓ | ARM64 servers, Raspberry Pi 4/5 64-bit |
| macOS (Apple Silicon) | ✓ | ✓ | Development; not recommended for mainnet pools |
| macOS (Intel) | ✓ | ✓ | Development; not recommended for mainnet pools |
| Windows | partial | — | Some Unix-only features (query, submit-tx) gated behind cfg(unix) |
A production stake pool should run on Linux on a server-class CPU with at least 16 GB RAM, 500 GB SSD, and a stable network connection.