Binary

The binary orchestrator manages a single executable via a systemd service unit.

Getting Started

1. Create a Systemd Unit Template

Write a systemd.service unit template. Use ${GENERATION_DIR} and ${DATA_DIR} as placeholders:

systemd.service

[Unit]
Description=My Server

[Service]
ExecStart=${GENERATION_DIR}/my-server
WorkingDirectory=${DATA_DIR}
Restart=on-failure

[Install]
WantedBy=multi-user.target

The [Install] section is required for the unit to start automatically after a reboot. The WantedBy= directive determines which systemd target pulls the service in during boot. Systemd respects all ordering and dependency directives (After=, Requires=, etc.) declared in the [Unit] section.

2. Pack the Bundle

Use rugix-bundler to package the binary and service unit into an app bundle:

rugix-bundler apps pack binary \
    --app my-app \
    --service systemd.service \
    my-server \
    my-app-v1.rugixb

This command:

1. Generates the app.toml manifest with orchestrator = "binary".
2. Packages the service unit template and any included files as an app-archive payload.
3. Packages the binary as a separate app-file payload for optimal delta updates.
4. Produces a Rugix Bundle.

Options:

• --service specifies the systemd unit template.
• --include adds extra files or directories to the bundle.

4. Install on the Device

rugix-ctrl apps install --bundle-hash <hash> my-app-v1.rugixb

This extracts the payloads, renders the unit template, installs the unit into systemd, and starts the service.

Generation Directory

The generation directory must contain:

• app.toml with orchestrator = "binary".
• systemd.service unit template.
• The executable binary itself (or any files the unit references).

Template Placeholders

Placeholder	Replaced with
${GENERATION_DIR}	Absolute path to the generation directory.
${DATA_DIR}	Absolute path to the app's persistent data directory.

Lifecycle Operations

Operation	Implementation
activate	Renders the unit template, writes it to .rugix/systemd/units/ in the generation directory and /run/systemd/system/, runs daemon-reload, then systemctl enable --runtime and systemctl start.
status	Maps systemctl is-active output to running/stopped/failed/unknown.
deactivate	Runs systemctl stop and systemctl disable --runtime, removes the runtime unit file, runs daemon-reload.
start	Runs systemctl start.
stop	Runs systemctl stop.

Boot behavior after stop: systemctl stop stops the service but does not disable it. The unit remains enabled via runtime symlinks, so systemd restarts the service on the next boot (once the unit has been restored and re-enabled by restore-units).

Boot-Time Restoration

Since /run/ is a tmpfs, systemd units installed there do not survive reboots. A oneshot service restores them on boot. See Systemd Integration for details.