Alphie Runner – Remote Deploy

1. What this script does

The runner deploy script is designed to run on your controller or admin workstation. It connects to one or more remote Linux hosts over SSH and turns them into Alphie runners.

For each target host, the script:

• Connects over SSH as an admin user (for example root or ubuntu).
• Copies a small installer script to the remote host and executes it with sudo/dzdo/doas/su as needed.
• Creates (or reuses) a dedicated runner user (default alphie).
• Sets up SSH key–only access for that runner user from your controller.
• Installs Podman and supporting packages for running Alphie workload containers.
• Prepares directories under /var/alphie for workspaces, logs, and runtime state.
• Configures rootless Podman for the runner user so containers run as that non-root account.
• Optionally:
  • Refreshes package metadata and performs OS upgrades.
  • Opens the firewall for SSH and/or a new SSH port.
  • Applies SELinux labels (container_file_t) to /var/alphie.
  • Changes the SSH daemon port on the runner host.
• Installs a health-check utility alphie-runner-health on the runner.
• Generates a per-host SSH keypair on the controller and adds a matching Host entry to your local ~/.ssh/config for easy access.

2. Prerequisites

On the machine where you run the script (controller/admin box)

• A Linux system with:
  • bash
  • ssh and scp
  • ssh-keygen
• Network connectivity to all runner hosts on their SSH port.
• Credentials that allow SSH login as an admin user (for example ubuntu, root, etc.).

On the target runner hosts

• Linux distribution with one of:
  • RHEL / Rocky / Alma / CentOS (with dnf or yum)
  • Debian / Ubuntu (with apt-get)
• SSH server running and reachable from the controller.
• An admin account that can escalate with sudo, dzdo, doas, or su.

3. How the script works (high level)

3.1 Local side

• Prompts you for:
  • Targets (hostnames/IPs or a file containing one host per line).
  • SSH port to use for the initial connection (default 22).
  • Remote admin username (default ubuntu).
  • Privilege escalation method (sudo, dzdo, doas, su, or none).
  • Runner username to create/use (default alphie).
  • Whether to update/upgrade packages on the runner.
  • Whether to touch the firewall and SELinux labels.
  • Whether to change the runner’s SSH port after setup.
• Generates one SSH keypair per target host (under ~/.ssh/alphie/<host>/) unless one already exists.
• Builds a small installer script and copies it + the controller’s public key to each target.
• Executes the remote installer via your chosen escalation method.
• Adds a Host alphie-<host> entry to your ~/.ssh/config pointing at the runner user, host, port, and keyfile.
• Runs a test health check using alphie-runner-health on the remote host.

3.2 Remote side (on the runner host)

For each runner host, the remote installer script:

• Detects the package manager (dnf, yum, or apt-get).
• Optionally refreshes metadata and performs a full OS upgrade.
• Installs required packages:
  • Podman and rootless dependencies (slirp4netns, fuse-overlayfs, uidmap on Debian/Ubuntu, etc.).
  • SSH server, git, rsync, tar, jq, curl.
• Creates or reuses the runner user and group (for example alphie).
• Creates /var/alphie/ws, /var/alphie/logs, and /var/alphie/run, owned by the runner user.
• Sets up ~runner/.ssh and adds the controller's public key to authorized_keys.
• Configures an SSH Match User block so that runner logins only use public-key auth (no passwords).
• Optionally changes the SSHD port and opens the firewall accordingly.
• Optionally applies SELinux container_file_t labels to /var/alphie.
• Configures rootless Podman for the runner user:
  • Ensures /etc/subuid and /etc/subgid entries exist.
  • Sets SUID bit on newuidmap/newgidmap if present.
  • Enables loginctl enable-linger for the runner user (if systemd is present).
  • Smoke-tests podman info under the runner account.
• Installs /usr/local/bin/alphie-runner-health, which reports CPU, load averages, memory, and rootless Podman status for the runner user.

4. How to run the script

1. Copy the script to your controller/admin box:

   scp deploy_alphie_runner_remote.sh user@controller:/path/to/

2. Log into the controller/admin box and make the script executable:

   chmod +x deploy_alphie_runner_remote.sh

3. Run it:

   ./deploy_alphie_runner_remote.sh

4. Answer the prompts (see next section for details).

5. Questions the script will ask

5.1 Targets

Prompt:

Enter target hostnames/IPs (space-separated) OR a path to a file with one host per line:

• You can paste a list such as:

  runner1.example.com runner2.example.com 10.10.10.5

• Or specify a file with one host per line:

  /path/to/runner_hosts.txt

5.2 SSH connection details

• SSH port for initial connection (default 22)
• Remote admin username to connect as (default ubuntu)
• Privilege escalation method:

  sudo / dzdo / doas / su / none

  Default is sudo. Use none only if you are already root on the remote side.

5.3 Runner user

Prompt:

Runner username to create/use [alphie]:

• Default is alphie.
• If the group already exists, the script attaches the user to that group and avoids the common “group exists” error.

5.4 Package refresh and upgrade

• Refresh package metadata on runner (recommended)?
  Controls whether the script runs dnf makecache, yum makecache, or apt-get update before installing packages.
• Perform full OS package upgrade on runner?
  If enabled, the script runs dnf upgrade, yum update, or apt-get upgrade.

5.5 Firewall and SELinux

• Open firewall for SSH on runner?
  If firewalld or ufw is present, the script opens either the standard SSH service or the new SSH port you specify.
• Apply SELinux labels for /var/alphie (container_file_t)?
  On SELinux-enabled systems, this adds a context rule and runs restorecon on /var/alphie.

5.6 Changing the SSH port

Prompt:

Change runner's sshd port after setup? (leave blank for no change):

• Leave blank to keep the existing SSH port.
• Enter a port number (for example 2222) to have the script:
  • Update /etc/ssh/sshd_config on the runner host.
  • Restart the SSH service.
  • Open the new port in the firewall (if configured).
  • Use the new port for the host’s entry in your local ~/.ssh/config.

6. What you get after it finishes

6.1 On the runner host

• A dedicated runner user (default alphie), with home directory and SSH key-only login.
• Work directories:
  • /var/alphie/ws – workspaces
  • /var/alphie/logs – logs
  • /var/alphie/run – runtime state
• Podman installed and configured for rootless use under the runner user.
• Optional firewall, SELinux, and SSH port configuration applied.
• /usr/local/bin/alphie-runner-health installed:

  alphie-runner-health alphie

  prints:
  • Line 1: CPU count
  • Line 2: load averages (1, 5, 15 minutes)
  • Line 3: total and free memory in MB
  • Line 4: Podman status (OK, ERR, or NOUSER)

6.2 On the controller/admin box

• Per-host SSH keypairs under:

  ~/.ssh/alphie/<sanitized-host>/id_rsa

• A matching entry in ~/.ssh/config for each runner, for example:

  Host alphie-runner1.example.com
      HostName runner1.example.com
      User alphie
      Port 22
      IdentityFile ~/.ssh/alphie/runner1.example.com/id_rsa
      IdentitiesOnly yes

• You can then SSH directly as:

  ssh alphie-runner1.example.com

  or explicitly:

  ssh -i ~/.ssh/alphie/<host>/id_rsa alphie@<host>

Once runners are prepared, you can point your Alphie controller at them using these credentials and ports when you register runner endpoints in the Alphie UI.