Skip to content
ryanbekhenPublic

About

Self-hosted container platform for a handful of machines

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Armada logo

Armada

Turn a few Linux machines into a container platform.
Apps with HTTPS, rolling updates, autoscaling, jobs, and volumes, on machines you already have.

CI Release License: Apache 2.0 Go version

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.

In one minute

# 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 request

Ship 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.10

Every 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: /health
armada app deploy web --file web.yaml --diff   # what would change
armada app deploy web --file web.yaml --wait

Install

The 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" sh

ARMADA_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.

Why Armada

  • Small and complete. armadad runs on every machine and brings its own container runtime, state store, and proxy. armada is 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 yaml exports what runs, and --diff shows a change before it happens.

Features

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.

Learn

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

Requirements

  • 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 armada client runs on Linux and macOS, and on Windows inside WSL 2.

Armada is tested on real machines before each release.

Contributing

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.

License

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.

About

Self-hosted container platform for a handful of machines

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages