Docs

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:

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, so localhost:8080 reaches it.
  • stop-grace-period is how long a replaced worker may keep running to finish its jobs.
  • health-check tells Alien when a new version is ready.

Prerequisites

  • The Alien CLI, signed in: curl -fsSL https://alien.dev/install | sh, then alien 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 and cargo-zigbuild itself. On macOS, brew install zig.
  • A Linux machine with systemd, on x86_64, where you have sudo. 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, run dnf install -y containerd wireguard-tools nftables first.

Get the example

alien init bare-metal-worker
cd bare-metal-worker

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

alien link

This 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:

  1. Set Command name to acmectl.
  2. Under Advanced → Platforms, keep Linux · x64 checked.
  3. 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 release

This 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 ls

Continue when the CLI package is ready. In the dashboard, Artifacts shows it as Healthy.

Create the deployment

alien deploy --name lab --machines

This 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 started

Join 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 ready

On 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 release

The 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-1 still answers, with "status":"running" and "version":"0.1.0".
  • curl localhost:8080/healthz returns 503 with "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 production

Promoting 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/lab

Then remove the machine agent from the machine:

sudo acmectl leave --purge

Next

On this page