Quickstart
This quickstart for Bare metal & on-prem runs a job worker written in Rust on a Linux machine you own. You build and ship it, set up the machine with one command, then ship a new version while a job is running and roll back.
The whole stack is one file, alien.toml:
name = "acme-jobs"
platforms = ["machines"]
[pool.workers]
cpu = 2
memory = "4Gi"
machines = { default = 1, allowed = [1, 20] }
[daemon.job-worker]
build = { toolchain = "rust", binary-name = "job-worker" }
pool = "workers"
runtime = { network-mode = "host" }
stop-grace-period = "1h"
health-check = { port = 8080, path = "/healthz" }platforms = ["machines"]deploys to machines you join, not to a cloud account or a Kubernetes cluster.[pool.workers]sets what each machine in the pool must have. The join command checks it before it installs anything.[daemon.job-worker]runs one copy of the worker on every machine in the pool. Alien builds it from source as a static Linux binary.network-mode = "host"puts the worker on the machine's own network, solocalhost:8080reaches it.stop-grace-periodis how long a replaced worker may keep running to finish its jobs.health-checktells Alien when a new version is ready.
Prerequisites
- The Alien CLI, signed in:
curl -fsSL https://alien.dev/install | sh, thenalien login. See Install the CLI. - Rust and Zig on your laptop. Alien cross-compiles the worker to a static Linux binary with
cargo zigbuild, and installs the Rust target andcargo-zigbuilditself. On macOS,brew install zig. - A Linux machine with systemd, on
x86_64, where you havesudo. A VM works. It needs outbound HTTPS, at least 2 CPUs and 4 GiB of memory, and about 17 GiB free under/var/lib/containerd. - On that machine,
containerd,wireguard-tools,nftables, and the WireGuard kernel module. On Debian and Ubuntu the machine agent installs the packages; on Fedora, RHEL, or Amazon Linux, rundnf install -y containerd wireguard-tools nftablesfirst.
Get the example
alien init bare-metal-worker
cd bare-metal-workerThis downloads the bare-metal worker example: alien.toml, a Rust crate, and its tests. The worker takes jobs over HTTP on port 8080 and runs them in the process. When a new release replaces it, it stops taking jobs, finishes the running ones, and exits.
Link the project
alien linkThis creates a project for the directory, or links it to an existing one. It suggests the directory name, bare-metal-worker, as the project name.
Name the setup CLI
The join command installs your setup CLI, a white-labeled build of the Alien deploy CLI under your command name. Alien builds it for every release.
In the dashboard, open project Settings → Artifacts → CLI:
- Set Command name to
acmectl. - Under Advanced → Platforms, keep Linux · x64 checked.
- Click Save changes.
From the CLI, the same change is alien projects packages update --file patch.json with {"cli": {"enabled": true, "name": "acmectl"}}. See Setup packages.
Release the first version
alien releaseThis builds the worker from source, creates release 1, and moves the production channel to it. Alien then builds the setup CLI for that release, which takes a few minutes. Check it:
alien packages lsContinue when the CLI package is ready. In the dashboard, Artifacts shows it as Healthy.
Create the deployment
alien deploy --name lab --machinesThis creates a deployment named lab, in a deployment group also named lab, so its full name is lab/lab. It prints the join command:
Machines deployment is ready to join hosts.
curl -fsSL 'https://pkg.alien.dev/acme/bare-metal-worker/install.sh?version=1.0.0' | sudo bash -s -- join --token 'aj1_...'The deployment's status is Waiting for machines until the first machine joins.
If the CLI package isn't ready yet, alien deploy fails with PLATFORM_READINESS_FAILED and names the missing check, such as DEPLOY_CLI_LINUX_X64_ARTIFACT. Wait for the package and run it again.
Join the machine
On the Linux machine, run the printed command. The script installs acmectl, the alien-deploy binary under your command name, and runs acmectl join:
Joining machine
[1/6] Resolving machine bundle
[2/6] Downloading machine bundle
[3/6] Installing bundle files
[4/6] Writing machine configuration
[5/6] Installing machine service
[6/6] Waiting for machine registration
Machine <machine-id>
✔ Machine service installed and startedJoin checks the machine first: systemd, the architecture, WireGuard, the packages, and the pool's CPU, memory, and disk. It then installs the machine agent as the alien-machine systemd service and waits up to 120 seconds for the machine to register.
Run a job
From your laptop, wait for the deployment:
alien deployments wait lab/lab --for readyOn the machine, check the worker and start a job that takes five minutes:
curl localhost:8080/healthz
curl -X POST localhost:8080/jobs -d '{"task":"wait","seconds":300}'{"status":"ok","version":"0.1.0"}
{"id":"j-1","status":"queued"}curl localhost:8080/jobs/j-1 shows the job running on version 0.1.0.
Release while the job runs
Set version = "0.2.0" in Cargo.toml, then release:
alien releaseThe release reaches the machine within about a minute, while j-1 is still running. The old worker gets the stop signal and finishes its job first:
curl localhost:8080/jobs/j-1still answers, with"status":"running"and"version":"0.1.0".curl localhost:8080/healthzreturns503with"status":"draining", and new jobs are refused.
When j-1 finishes, the old worker exits and 0.2.0 starts a few seconds later. curl localhost:8080/healthz now prints "version":"0.2.0". The new worker starts with an empty job list, because this example keeps jobs in memory. You didn't touch the machine: the machine agent pulled the release over outbound HTTPS.
A job is never cut short as long as it ends within stop-grace-period. The worker's logs are in the dashboard: open the deployment under Deployments.
Roll back
List the releases and promote the first one again:
alien releases ls
alien releases promote <release-1-id> --channel productionPromoting reuses the release's artifacts, so nothing is rebuilt. The machine goes back to 0.1.0 the same way it moved forward.
Clean up
alien deployments delete lab/labThen remove the machine agent from the machine:
sudo acmectl leave --purgeNext
- Add to your product: give a customer the join command for their on-prem machines
- Workloads: privileged daemons, containers, data, and domains
- Releases and operations: channels, drain, logs, and offline machines