Zhuiri

Personal deployment kit for running a Forgejo action runner on rootless Podman via systemd Quadlet. Built for use with forge.marvin8.zone repositories.

Why Zhuiri?

追日 (zhuīrì) means "chasing the sun" in Mandarin — relentless, tireless forward motion. A CI runner never stops: it picks up every job, it runs without rest. The name doubles as the runner label in workflow YAML:

runs-on: zhuiri

Prerequisites

• Rootless Podman installed
• Systemd user session active at boot:

  loginctl enable-linger $USER
  

• Podman socket enabled:

  systemctl --user enable --now podman.socket
  

  On NixOS the podman user unit is not installed into the systemd user search path, so the command above fails. Create it as a real file at ~/.config/systemd/user/podman.socket — never symlink into /nix/store, the target vanishes on podman upgrades and leaves a dead socket:

  [Unit]
  Description=Podman API Socket
  Documentation=man:podman-system-service(1)
  
  [Socket]
  ListenStream=%t/podman/podman.sock
  SocketMode=0660
  
  [Install]
  WantedBy=sockets.target
  

  Then:

  systemctl --user daemon-reload
  systemctl --user enable --now podman.socket
  

• Runner UUID and token from your Forgejo instance: forge.marvin8.zone: Admin panel → Runners → Create Runner, or repo/org Settings → Runners

Setup

git clone https://forge.marvin8.zone/marvin8/zhuiri.git
cd zhuiri
just setup
# Edit ~/.config/zhuiri/config.yml — fill in uuid and token
systemctl --user enable --now zhuiri.service

Day-to-day

just status    # service status
just logs      # follow logs
just restart   # restart after config changes
just stop      # stop the runner

License

AGPL-3.0-or-later