Systemd Service

Generic systemd user service management: idempotently create, start, stop, restart, and remove a persistent user service for any command line — and audit every service model against the live host in one call. WHAT IT DOES

A thin, generic wrapper around systemctl --user and unit-file rendering. You give it a service name and the exact command line to run, and it stands up a persistent background service — idempotently, so re-running is safe. It is the reusable building block other extensions call to keep a long-lived process (a web service, an API, a queue server) alive: rather than embedding systemd logic in every extension, they invoke this model's methods. Because these are user units, startService also enables user lingering so the service starts at boot, not merely at login. The audit method answers "what does swamp expect, what actually exists, and what state is it in?" in one command: every model of this type, its systemd unit state, declared and live TCP ports, stale reported state, drift, and orphan managed units.

INSTALL

swamp extension pull @svendowideit/systemd-service

DEPENDENCIES

None. It shells out to systemctl --user, loginctl, and (for audit) ss and cgroup v2, which ship with systemd; no other extension, package, or service is required.

RUN

# Create (or update) the unit for feedback-server and start it at boot.
swamp model @svendowideit/systemd-service method run createService feedback-server \
  --input 'serviceName=feedback-server' \
  --input 'command=~/.swamp/deno/deno run --allow-net scripts/feedback-server.ts' \
  --input 'workingDirectory=~/.swamp/pulled-extensions/@svendowideit/news/files'

swamp model @svendowideit/systemd-service method run startService feedback-server \
  --input 'serviceName=feedback-server'

# Check it, restart it (e.g. after replacing its executable), stop it, or
# remove it entirely.
swamp model @svendowideit/systemd-service method run status feedback-server
swamp model @svendowideit/systemd-service method run restartService feedback-server \
  --input 'serviceName=feedback-server'
swamp model @svendowideit/systemd-service method run stopService feedback-server \
  --input 'serviceName=feedback-server'

# Audit every service model against the live host in one call: each
# model, its systemd unit, state, ports, drift, and orphan units.
swamp model @svendowideit/systemd-service method run audit feedback-server
swamp data get feedback-server audit --json

# Or run the bundled workflow, which needs no model name and prints an
# aligned table to the log (default: every model; --input service=… for one).
swamp workflow run @svendowideit/systemd-service-audit
swamp workflow run @svendowideit/systemd-service-audit \
  --input service=feedback-server

CONFIGURE

Global arguments (set at model creation with --global-arg):

denoPath     Path to the Deno binary for Deno services  (default ~/.swamp/deno/deno)
unitDir      Directory for systemd user unit files     (default ~/.config/systemd/user)
cgroupRoot   cgroup v2 mount point used by `audit`     (default /sys/fs/cgroup)

Per-call overrides on createService: command, description, workingDirectory, environment, restart, restartSec, after, wants, and force. startService takes linger (default true) to control whether user lingering is enabled. restartService restarts a running (or stopped) unit and verifies it is active — use it after replacing the service's executable, which enable --now does not restart. audit takes one optional input, serviceName (default all): all reports every model of this type, any other value limits the report to the model whose name or managed unit matches it and errors if none is found. The bundled workflow exposes this as --input service=….

WHAT IT INSTALLS

A single systemd user unit file per service at <unitDir>/<name>.service. startService enables the unit and user lingering so it starts at boot. restartService restarts it in place. removeService deletes the unit file. Nothing else is installed.