Turn a few Linux machines into a container platform.
Apps with HTTPS, rolling updates, autoscaling, jobs, and volumes, on machines you already have.
Quickstart · Documentation · Guides · CLI reference · Spec reference · Releases
Note
Armada is in alpha. It is tested end to end on real machines before every release, but specs, flags, and the state format may still change between releases.
# On each machine: install
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh
# On the first machine: create the cluster
sudo armadad init
sudo systemctl enable --now armada-server
armada cluster update --acme-email you@example.com --root-domain apps.example.com
# Deploy an app: two replicas behind HTTPS
armada app deploy web --image traefik/whoami:v1.10 --port 80 --ingress external --min 2 --wait
curl https://web.apps.example.com # answers with the replica's name and the requestShip a new version, watch it roll out, and go back if you need to:
armada app deploy web --image traefik/whoami:v1.11 --wait
armada app rollback web # back to v1.10Every example works as written: traefik/whoami
answers on port 80 with who it is and what it received. Put your own image and
port in its place. Keep the app as a file in git and change it from there:
# web.yaml, from: armada app show web -o yaml
name: web
image: traefik/whoami:v1.11
ingress:
type: external
port: 80
env:
- name: WHOAMI_NAME
value: web
scale:
min: 2
max: 10
rules:
- type: http
concurrent: 50
probes:
readiness:
path: /healtharmada app deploy web --file web.yaml --diff # what would change
armada app deploy web --file web.yaml --waitThe same script installs Armada everywhere. It verifies what it downloads and installs or upgrades only: it never sets a machine up by itself.
| Where | What gets installed | Command |
|---|---|---|
| A Linux machine of the cluster | armadad (runs the machine) and the armada client |
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh |
| Your Linux laptop, a CI runner, any Linux machine that only manages the cluster | The armada client only (a download of a few MB) |
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo ARMADA_CLIENT_ONLY=1 sh |
| macOS (Intel or Apple silicon) | The armada client only (always on macOS) |
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo sh |
| Windows 10 or 11 | The Linux armada client inside WSL 2 (there is no native Windows client) |
In a WSL 2 shell (Ubuntu, for example): curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | sudo ARMADA_CLIENT_ONLY=1 sh |
Without root, install the client into your home directory instead:
curl -fsSL https://raw.githubusercontent.com/ryanbekhen/armada/main/install.sh | ARMADA_CLIENT_ONLY=1 ARMADA_PREFIX="$HOME/.local" shARMADA_VERSION=v0.1.0-alpha.6 pins a version. The client then needs a
certificate of your own and a way to reach the control plane's private
address (a VPN or an SSH tunnel): see
Use armada from your own computer.
- Small and complete.
armadadruns on every machine and brings its own container runtime, state store, and proxy.armadais the client, for Linux and macOS, and needs no root. - Safe by default. HTTPS with automatic certificates, rolling updates that send traffic only to ready replicas, drained shutdowns, confined containers, encrypted secrets, and mTLS between every component.
- Grows with you. Start on one machine. Add nodes with a one-time token, and two more servers for a control plane that survives losing one.
- Everything is a spec. Apps and jobs are YAML files you keep in git.
armada app show -o yamlexports what runs, and--diffshows a change before it happens.
| Deploy | Rolling updates, rollback, revisions pinned to image digests, traffic splitting for canaries and previews |
| Traffic | HTTPS on every node, custom domains, internal services by name (http://<app>, <app>.internal), internal TCP for databases, IP allow and deny lists, CORS, sticky sessions |
| Scale | Autoscaling on requests, CPU, memory, queue length, or a schedule; scale to zero and back on the next request |
| Run | Jobs and cron jobs, jobs started by a queue, init containers, sidecars, exec into replicas, logs with a searchable history, sent to Loki or OTLP |
| Data | Volumes, scheduled encrypted backups to an S3-compatible bucket, failover to another node, NFS exports |
| Network | Containers reachable at their own address on every node, isolation between apps and spaces, encryption between nodes, clusters of machines with only public addresses over a WireGuard mesh, and clusters across sites |
| Operate | Highly available control plane with scheduled encrypted backups to a bucket, self-healing, placement by labels, spaces, users and roles, events, alerts to Slack, Discord, Telegram, or email, Prometheus metrics, verified upgrades |
Read the full feature list.
| Quickstart | From empty machines to an app on HTTPS |
| Concepts | Apps, revisions, replicas, nodes, spaces: how Armada thinks |
| Guides | Complete recipes: a web app, a database, workers, cron jobs, canaries, CI/CD, and more |
| CLI reference | Every armada and armadad command and flag |
| Spec reference | Every field of an app or job spec |
| Operations guide | Running a cluster day to day: upgrades, backups, nodes, networking, monitoring |
| Security | The threat model, and how to report a vulnerability |
- Linux machines (amd64 or arm64): cloud instances, VMs, or bare metal, with systemd and a private network between them, or only public addresses, joined over a WireGuard mesh (guide).
- A domain whose DNS you control, for HTTPS.
- The
armadaclient runs on Linux and macOS, and on Windows inside WSL 2.
Armada is tested on real machines before each release.
Bug reports, ideas, and pull requests are welcome. CONTRIBUTING.md explains how to build Armada and run its tests, and the architecture decisions explain why it works the way it does.
Apache License 2.0: free to use, change, and sell, also commercially. Armada's dependencies and the container runtime it embeds are under licenses that allow the same; THIRD_PARTY_NOTICES.md lists them and what passing Armada on requires.