refactor(container): move companion UIs to systemd via Quadlet
Companion UI containers (archy-bitcoin-ui, archy-lnd-ui, archy-electrs-ui) used to be launched as fire-and-forget tokio::spawn blocks from install.rs. If archipelago crashed mid-spawn or the container's cgroup was reaped, companions vanished from podman ps -a and only a manual rm/run could bring them back (the .228 incident). Now each companion is rendered as a Quadlet .container unit under ~/.config/containers/systemd/, daemon-reloaded, and started via systemctl --user. systemd owns supervision from that point on: - archipelago can crash, restart, or be uninstalled without touching any companion. - Quadlet's Restart=always + RestartSec=10 handles container exits. - A 30s reconcile tick in boot_reconciler enumerates expected companion units and re-installs any whose unit file or service vanished — defense-in-depth against external tampering. New module layout: - container/quadlet.rs: pure unit renderer + atomic write_if_changed + systemctl helpers (daemon_reload_user / enable_now / disable_remove / is_active). 6 unit tests, no I/O in the renderer. - container/companion.rs: per-app companion specs, install/remove/ reconcile, image presence (build local first, fall back to insecure registry only via image_uses_insecure_registry whitelist). 2 tests. install.rs handle_package_install now ends with a single call to companion::install_for(package_id), replacing 287 lines of spawn-and- hope shellouts plus a ~120-line nginx auth-injector helper that worked around per-node RPC password baking. The helper is gone too — the pre-start hook renders the per-node nginx.conf to /var/lib/archipelago/ bitcoin-ui/nginx.conf and the Quadlet unit bind-mounts it read-only. runtime.rs handle_package_uninstall now disables companions before the container rm loop. Otherwise systemd's Restart=always would respawn each companion within ~10s of removal. Tests: 53 container tests pass, including 6 quadlet renderer tests (host network, bridge network, capability set, atomic write idempotence) and 2 companion specs (per-app companion lookup, build_unit shape). boot_reconciler tests gain a #[cfg(test)] without_companion_stage() flag so the paused-clock fixtures don't race the real systemctl I/O. A bats regression test (companion-survives-archipelago-restart.bats, gated on ARCHY_ALLOW_DESTRUCTIVE=1) asserts the .228 failure mode cannot recur: every installed companion has a unit file, services stay active across systemctl --user restart archipelago, and a deleted unit file is recreated within one reconcile tick. Net delta: +941 / -363, but the +941 is mostly tests (~440 lines) and the new declarative layer; the imperative tokio::spawn block and its nginx-auth helper are gone, removing two failure classes (orphan companions on archipelago crash, and post-start exec races under tightly-confined cgroups) that previously needed manual SSH recovery. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
archipelago
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
2bf8181110
commit
23c4e7441f
@@ -0,0 +1,371 @@
|
||||
//! Render and lifecycle Quadlet `.container` units for companion UI
|
||||
//! containers (archy-bitcoin-ui, archy-lnd-ui, archy-electrs-ui).
|
||||
//!
|
||||
//! Why Quadlet: companions used to run as fire-and-forget `tokio::spawn`
|
||||
//! blocks from `install.rs`. If archipelago crashed mid-spawn or the
|
||||
//! kernel reaped a parent cgroup, companions vanished from `podman ps`
|
||||
//! entirely and only a manual `podman run` brought them back. Putting the
|
||||
//! unit on disk and letting systemd own start/restart removes that whole
|
||||
//! class of failure: the daemon is now systemd, archipelago is just the
|
||||
//! provisioner.
|
||||
//!
|
||||
//! Design constraints kept this module small on purpose:
|
||||
//!
|
||||
//! - **Single responsibility**: render → write → enable → disable. We do
|
||||
//! NOT pull images here — the caller is expected to have the image
|
||||
//! present locally (companions either build from `/opt/archipelago/docker/`
|
||||
//! or are pre-pulled by `install_companion_image`). The quadlet unit
|
||||
//! declares `Pull=never` so a missing image surfaces immediately
|
||||
//! instead of silently retrying behind systemd's restart loop.
|
||||
//! - **Atomic writes**: `tempfile + rename` so a partially-written unit
|
||||
//! is never visible to systemd. A daemon-reload during a rolling
|
||||
//! update can't see half a file.
|
||||
//! - **Idempotent**: `write_if_changed` compares bytes before touching
|
||||
//! the file. No daemon-reload, no service-restart cascade if the
|
||||
//! rendered bytes match what's on disk.
|
||||
//! - **systemctl --user only**: archipelago runs as uid=1000 with
|
||||
//! linger enabled. We never touch the system bus from here.
|
||||
//!
|
||||
//! See `docs/rust-orchestrator-migration.md` and the failure-mode log in
|
||||
//! `feedback_container_lifecycle_failure_modes.md` for the incident
|
||||
//! that motivated the move.
|
||||
|
||||
use anyhow::{anyhow, Context, Result};
|
||||
use std::fmt::Write as _;
|
||||
use std::path::{Path, PathBuf};
|
||||
use tokio::fs;
|
||||
use tokio::process::Command;
|
||||
|
||||
/// Default rootless quadlet directory. Resolved per-user at runtime via
|
||||
/// `unit_dir()`. Tests pass an explicit dir.
|
||||
pub const DEFAULT_REL_UNIT_DIR: &str = ".config/containers/systemd";
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct BindMount {
|
||||
pub host: PathBuf,
|
||||
pub container: PathBuf,
|
||||
pub read_only: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
#[allow(dead_code)] // Bridge is reserved for Phase 5 per-app network isolation.
|
||||
pub enum NetworkMode {
|
||||
#[default]
|
||||
Host,
|
||||
/// A user-defined podman network — quadlet creates the container
|
||||
/// attached to it. The network must already exist (orchestrator's
|
||||
/// `ensure_container_network` handles that on every reconcile tick).
|
||||
Bridge(String),
|
||||
}
|
||||
|
||||
/// One Quadlet `.container` unit. Field set is deliberately small —
|
||||
/// add a new field only when a companion actually needs it.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct QuadletUnit {
|
||||
pub name: String,
|
||||
pub description: String,
|
||||
pub image: String,
|
||||
pub network: NetworkMode,
|
||||
pub user: Option<String>,
|
||||
pub memory_mb: Option<u32>,
|
||||
pub cap_drop_all: bool,
|
||||
pub cap_add: Vec<String>,
|
||||
pub bind_mounts: Vec<BindMount>,
|
||||
pub extra_podman_args: Vec<String>,
|
||||
pub depends_on: Vec<String>,
|
||||
}
|
||||
|
||||
impl QuadletUnit {
|
||||
/// File name on disk: `<name>.container`. Quadlet translates this
|
||||
/// into a `<name>.service` unit at daemon-reload time.
|
||||
pub fn unit_filename(&self) -> String {
|
||||
format!("{}.container", self.name)
|
||||
}
|
||||
|
||||
/// systemd service name created by Quadlet for this unit.
|
||||
pub fn service_name(&self) -> String {
|
||||
format!("{}.service", self.name)
|
||||
}
|
||||
|
||||
/// Render the canonical Quadlet unit text. Pure function — no I/O.
|
||||
pub fn render(&self) -> String {
|
||||
let mut s = String::with_capacity(512);
|
||||
let _ = writeln!(s, "# Generated by archipelago. DO NOT EDIT.");
|
||||
let _ = writeln!(s, "# Edits are overwritten on the next reconcile.");
|
||||
let _ = writeln!(s);
|
||||
let _ = writeln!(s, "[Unit]");
|
||||
let _ = writeln!(s, "Description={}", self.description);
|
||||
let _ = writeln!(s, "After=network-online.target");
|
||||
let _ = writeln!(s, "Wants=network-online.target");
|
||||
for dep in &self.depends_on {
|
||||
let _ = writeln!(s, "Requires={dep}");
|
||||
let _ = writeln!(s, "After={dep}");
|
||||
}
|
||||
let _ = writeln!(s);
|
||||
let _ = writeln!(s, "[Container]");
|
||||
let _ = writeln!(s, "ContainerName={}", self.name);
|
||||
let _ = writeln!(s, "Image={}", self.image);
|
||||
// Pull=never: companions are pre-pulled or built. A missing image
|
||||
// must surface as a unit start failure, not a silent retry storm.
|
||||
let _ = writeln!(s, "Pull=never");
|
||||
match &self.network {
|
||||
NetworkMode::Host => {
|
||||
let _ = writeln!(s, "Network=host");
|
||||
}
|
||||
NetworkMode::Bridge(net) => {
|
||||
let _ = writeln!(s, "Network={net}");
|
||||
}
|
||||
}
|
||||
if let Some(user) = &self.user {
|
||||
let _ = writeln!(s, "User={user}");
|
||||
}
|
||||
if self.cap_drop_all {
|
||||
let _ = writeln!(s, "DropCapability=ALL");
|
||||
}
|
||||
for cap in &self.cap_add {
|
||||
let _ = writeln!(s, "AddCapability={cap}");
|
||||
}
|
||||
if let Some(mb) = self.memory_mb {
|
||||
let _ = writeln!(s, "PodmanArgs=--memory={mb}m");
|
||||
}
|
||||
for bm in &self.bind_mounts {
|
||||
let mode = if bm.read_only { ":ro,Z" } else { ":Z" };
|
||||
let _ = writeln!(
|
||||
s,
|
||||
"Volume={}:{}{}",
|
||||
bm.host.display(),
|
||||
bm.container.display(),
|
||||
mode
|
||||
);
|
||||
}
|
||||
for arg in &self.extra_podman_args {
|
||||
let _ = writeln!(s, "PodmanArgs={arg}");
|
||||
}
|
||||
let _ = writeln!(s);
|
||||
let _ = writeln!(s, "[Service]");
|
||||
// Always restart with a 10s backoff. RestartSec keeps a
|
||||
// crash-loop from saturating the journal.
|
||||
let _ = writeln!(s, "Restart=always");
|
||||
let _ = writeln!(s, "RestartSec=10");
|
||||
let _ = writeln!(s);
|
||||
let _ = writeln!(s, "[Install]");
|
||||
let _ = writeln!(s, "WantedBy=default.target");
|
||||
s
|
||||
}
|
||||
}
|
||||
|
||||
/// Resolve the per-user quadlet dir under $HOME. Created if missing.
|
||||
pub async fn unit_dir() -> Result<PathBuf> {
|
||||
let home = std::env::var_os("HOME")
|
||||
.map(PathBuf::from)
|
||||
.ok_or_else(|| anyhow!("HOME not set; cannot locate quadlet unit dir"))?;
|
||||
let dir = home.join(DEFAULT_REL_UNIT_DIR);
|
||||
fs::create_dir_all(&dir)
|
||||
.await
|
||||
.with_context(|| format!("create_dir_all {}", dir.display()))?;
|
||||
Ok(dir)
|
||||
}
|
||||
|
||||
/// Atomically write `unit` into `dir/<name>.container` if the bytes
|
||||
/// differ from what's already there. Returns true if the file changed.
|
||||
pub async fn write_if_changed(unit: &QuadletUnit, dir: &Path) -> Result<bool> {
|
||||
let path = dir.join(unit.unit_filename());
|
||||
let new_bytes = unit.render();
|
||||
|
||||
if let Ok(old) = fs::read_to_string(&path).await {
|
||||
if old == new_bytes {
|
||||
return Ok(false);
|
||||
}
|
||||
}
|
||||
|
||||
fs::create_dir_all(dir)
|
||||
.await
|
||||
.with_context(|| format!("create_dir_all {}", dir.display()))?;
|
||||
let tmp = path.with_extension("container.tmp");
|
||||
fs::write(&tmp, new_bytes.as_bytes())
|
||||
.await
|
||||
.with_context(|| format!("write tmp {}", tmp.display()))?;
|
||||
fs::rename(&tmp, &path)
|
||||
.await
|
||||
.with_context(|| format!("rename {} -> {}", tmp.display(), path.display()))?;
|
||||
Ok(true)
|
||||
}
|
||||
|
||||
/// Reload the user systemd manager. Required after any quadlet write
|
||||
/// or removal so systemd picks up the generated `.service` translation.
|
||||
pub async fn daemon_reload_user() -> Result<()> {
|
||||
let status = Command::new("systemctl")
|
||||
.args(["--user", "daemon-reload"])
|
||||
.status()
|
||||
.await
|
||||
.context("spawn systemctl --user daemon-reload")?;
|
||||
if !status.success() {
|
||||
return Err(anyhow!("systemctl --user daemon-reload exited {status}"));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Enable + start a quadlet-generated service. `enable --now` makes it
|
||||
/// survive reboots and starts it immediately.
|
||||
pub async fn enable_now(service: &str) -> Result<()> {
|
||||
// Quadlet-generated units cannot be `enable`d directly because the
|
||||
// .service file lives under /run, not /etc — `enable` would refuse
|
||||
// ("transient or generated"). The unit's `[Install] WantedBy` is
|
||||
// honoured at daemon-reload, so we just start it.
|
||||
let status = Command::new("systemctl")
|
||||
.args(["--user", "start", service])
|
||||
.status()
|
||||
.await
|
||||
.with_context(|| format!("spawn systemctl --user start {service}"))?;
|
||||
if !status.success() {
|
||||
return Err(anyhow!("systemctl --user start {service} exited {status}"));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Stop + remove a quadlet unit and its on-disk file. Best-effort:
|
||||
/// errors stop only the destructive write at the failing step so a
|
||||
/// partial removal doesn't leave a quadlet file pointing at a service
|
||||
/// that systemd no longer knows about.
|
||||
pub async fn disable_remove(unit_name: &str, dir: &Path) -> Result<()> {
|
||||
let svc = format!("{unit_name}.service");
|
||||
// Stop first; ignore failure (unit may already be down).
|
||||
let _ = Command::new("systemctl")
|
||||
.args(["--user", "stop", &svc])
|
||||
.status()
|
||||
.await;
|
||||
let path = dir.join(format!("{unit_name}.container"));
|
||||
if fs::try_exists(&path).await.unwrap_or(false) {
|
||||
fs::remove_file(&path)
|
||||
.await
|
||||
.with_context(|| format!("remove {}", path.display()))?;
|
||||
}
|
||||
daemon_reload_user().await.ok();
|
||||
// Defensive: kill the actual container too, in case quadlet left it.
|
||||
let _ = Command::new("podman")
|
||||
.args(["rm", "-f", unit_name])
|
||||
.status()
|
||||
.await;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Is the quadlet-generated service currently active?
|
||||
pub async fn is_active(service: &str) -> bool {
|
||||
Command::new("systemctl")
|
||||
.args(["--user", "is-active", "--quiet", service])
|
||||
.status()
|
||||
.await
|
||||
.map(|s| s.success())
|
||||
.unwrap_or(false)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use tempfile::tempdir;
|
||||
|
||||
fn sample_unit() -> QuadletUnit {
|
||||
QuadletUnit {
|
||||
name: "archy-bitcoin-ui".into(),
|
||||
description: "Bitcoin RPC UI proxy".into(),
|
||||
image: "146.59.87.168:3000/lfg2025/bitcoin-ui:latest".into(),
|
||||
network: NetworkMode::Host,
|
||||
user: Some("0:0".into()),
|
||||
memory_mb: Some(128),
|
||||
cap_drop_all: true,
|
||||
cap_add: vec![
|
||||
"CHOWN".into(),
|
||||
"DAC_OVERRIDE".into(),
|
||||
"NET_BIND_SERVICE".into(),
|
||||
"SETUID".into(),
|
||||
"SETGID".into(),
|
||||
],
|
||||
bind_mounts: vec![BindMount {
|
||||
host: PathBuf::from("/var/lib/archipelago/bitcoin-ui/nginx.conf"),
|
||||
container: PathBuf::from("/etc/nginx/conf.d/default.conf"),
|
||||
read_only: true,
|
||||
}],
|
||||
extra_podman_args: vec![],
|
||||
depends_on: vec![],
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn render_contains_required_directives() {
|
||||
let s = sample_unit().render();
|
||||
assert!(s.contains("[Container]"));
|
||||
assert!(s.contains("ContainerName=archy-bitcoin-ui"));
|
||||
assert!(s.contains("Image=146.59.87.168:3000/lfg2025/bitcoin-ui:latest"));
|
||||
assert!(s.contains("Pull=never"));
|
||||
assert!(s.contains("Network=host"));
|
||||
assert!(s.contains("DropCapability=ALL"));
|
||||
assert!(s.contains("AddCapability=CHOWN"));
|
||||
assert!(s.contains("AddCapability=NET_BIND_SERVICE"));
|
||||
assert!(s.contains("PodmanArgs=--memory=128m"));
|
||||
assert!(s.contains(
|
||||
"Volume=/var/lib/archipelago/bitcoin-ui/nginx.conf:/etc/nginx/conf.d/default.conf:ro,Z"
|
||||
));
|
||||
assert!(s.contains("[Service]"));
|
||||
assert!(s.contains("Restart=always"));
|
||||
assert!(s.contains("WantedBy=default.target"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn render_bridge_network_emits_network_name() {
|
||||
let mut u = sample_unit();
|
||||
u.network = NetworkMode::Bridge("archy-bitcoin-ui-net".into());
|
||||
let s = u.render();
|
||||
assert!(s.contains("Network=archy-bitcoin-ui-net"));
|
||||
assert!(!s.contains("Network=host"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unit_filename_and_service_name_are_consistent() {
|
||||
let u = sample_unit();
|
||||
assert_eq!(u.unit_filename(), "archy-bitcoin-ui.container");
|
||||
assert_eq!(u.service_name(), "archy-bitcoin-ui.service");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn write_if_changed_writes_first_time_then_noops() {
|
||||
let dir = tempdir().unwrap();
|
||||
let u = sample_unit();
|
||||
let changed = write_if_changed(&u, dir.path()).await.unwrap();
|
||||
assert!(changed, "first write must report changed");
|
||||
let on_disk = tokio::fs::read_to_string(dir.path().join(u.unit_filename()))
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(on_disk.starts_with("# Generated by archipelago"));
|
||||
|
||||
let changed2 = write_if_changed(&u, dir.path()).await.unwrap();
|
||||
assert!(!changed2, "second write with identical bytes must no-op");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn write_if_changed_rewrites_when_field_changes() {
|
||||
let dir = tempdir().unwrap();
|
||||
let mut u = sample_unit();
|
||||
write_if_changed(&u, dir.path()).await.unwrap();
|
||||
|
||||
u.memory_mb = Some(256);
|
||||
let changed = write_if_changed(&u, dir.path()).await.unwrap();
|
||||
assert!(changed, "field change must trigger rewrite");
|
||||
let on_disk = tokio::fs::read_to_string(dir.path().join(u.unit_filename()))
|
||||
.await
|
||||
.unwrap();
|
||||
assert!(on_disk.contains("PodmanArgs=--memory=256m"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn write_if_changed_atomic_rename_leaves_no_tmp() {
|
||||
let dir = tempdir().unwrap();
|
||||
write_if_changed(&sample_unit(), dir.path()).await.unwrap();
|
||||
let mut entries = tokio::fs::read_dir(dir.path()).await.unwrap();
|
||||
while let Some(e) = entries.next_entry().await.unwrap() {
|
||||
assert!(
|
||||
!e.file_name().to_string_lossy().ends_with(".tmp"),
|
||||
"atomic rename must leave no .tmp residue"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user