Appliance systemd target

Updated Oct 19, 2026

repovec-appliance ships a base systemd target and static daemon service files under packaging/systemd/:

  • repovec.target
  • repovecd.service
  • repovec-mcpd.service
  • [email protected]
  • repovec-provision.service

Install these files to /etc/systemd/system/, then reload systemd:

sudo install -m 0644 packaging/systemd/repovec.target /etc/systemd/system/repovec.target
sudo install -m 0644 packaging/systemd/repovecd.service /etc/systemd/system/repovecd.service
sudo install -m 0644 packaging/systemd/repovec-mcpd.service /etc/systemd/system/repovec-mcpd.service
sudo install -m 0644 packaging/systemd/[email protected] /etc/systemd/system/[email protected]
sudo install -m 0644 packaging/systemd/repovec-provision.service /etc/systemd/system/repovec-provision.service
sudo install -m 0644 packaging/tmpfiles.d/repovec.conf /usr/lib/tmpfiles.d/repovec.conf
sudo install -m 0644 packaging/sysusers.d/repovec.conf /usr/lib/sysusers.d/repovec.conf
sudo systemctl daemon-reload

The target wants qdrant.service, repovecd.service, repovec-mcpd.service, cloudflared.service, and repovec-provision.service. The Qdrant service name is the generated systemd unit from the installed /etc/containers/systemd/qdrant.container Quadlet; dependent services must use qdrant.service.

[email protected] is the template used for future per-repository indexer instances. It runs grepai watch as the repovec user, sets HOME=/var/lib/repovec, works in /var/lib/repovec/worktrees/%I, and writes stdout and stderr to journald. Later reconciliation work creates and manages concrete instances; operators should not expect installing the template alone to start indexers.

repovec-provision.service is a oneshot that runs systemd-sysusers on /usr/lib/sysusers.d/repovec.conf and then systemd-tmpfiles --create on /usr/lib/tmpfiles.d/repovec.conf, so the repovec system user and the data directory tree exist before any dependent service starts — including on a freshly installed host that has not been rebooted. Every dependent service declares Requires=repovec-provision.service, the oneshot's Before= line orders it ahead of those services, and repovec.target activates it. The Requires= directive is what makes provisioning mandatory: ordering on its own does not prevent a dependent service from starting when provisioning fails. The requirement is what makes the appliance fail closed on a host where the repovec user or the data tree could not be created. systemd-sysusers creates the account record but not the home directory; the tmpfiles.d asset creates the tree. Re-running the tools creates missing declarations and does not empty populated directories. It does not correct an existing repovec account or repair misowned existing children; those conditions require an operator to correct the account or child ownership separately.

The provisioning oneshot returns to inactive after success. Restarting repovec.target therefore runs it again, providing a supported way to reapply the account and directory declarations after updating the assets or repairing directory drift:

sudo systemctl restart repovec.target

To reapply provisioning directly, restart its unit. Systemd also restarts active consumers because they require this unit:

sudo systemctl restart repovec-provision.service

Enable and start the appliance service group with:

sudo systemctl enable repovec.target
sudo systemctl start repovec.target

Note: repovecd and repovec-mcpd validate the checked-in systemd unit contract, then the live directory-layout contract, then Qdrant liveness at startup before doing any other work. If validation fails, the daemon exits immediately with a non-zero exit code. Inspect the journal with journalctl -u repovecd.service --no-pager | tail -20 or journalctl -u repovec-mcpd.service --no-pager | tail -20; the error message identifies the violated unit contract, the directory-layout violation (with the offending path), or the Qdrant liveness condition. This validation does not prove that the host has /usr/bin/grepai, concrete worktrees, or a compatible systemd version.

Starting the target may fail until these prerequisites are present on the host:

  • The repovec system user exists and matches the checked-in unit contract.
  • /etc/repovec/qdrant-api-key has been provisioned with the Qdrant API key and can be read by the daemon services.
  • The required daemon binaries, repovecd and repovec-mcpd, exist at the paths referenced by the unit files.
  • qdrant.service can start and accept authenticated gRPC requests before the bounded daemon readiness wait expires.

If any prerequisite is missing, the target fails closed instead of starting partially configured services.