Appliance systemd target

Updated Jul 18, 2026

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

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 systemctl daemon-reload

The target wants qdrant.service, repovecd.service, repovec-mcpd.service, and cloudflared.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.

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 and 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 or 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.

Startup validation logging

Both repovecd and repovec-mcpd validate their checked-in systemd unit contracts at startup before starting any async work. The outcome is observable in the systemd journal:

Success — a TRACE-level event followed by a DEBUG-level confirmation:

TRACE systemd unit contract validated
DEBUG systemd unit contract validated at daemon startup

Failure — an ERROR-level event with structured fields identifying the violating unit and the nature of the failure, followed by a non-zero process exit:

ERROR systemd unit contract violation — aborting startup
  unit=repovecd.service
  error=repovecd.service is missing [Service]

The unit field contains the logical systemd unit name (e.g. repovecd.service) and the error field contains the human-readable description of the contract violation. The Qdrant Quadlet validator emits INFO, WARN, and ERROR events; use a target-scoped filter such as RUST_LOG=repovec_core::qdrant_quadlet=info to inspect those validation events. The systemd unit validator emits TRACE, DEBUG, and ERROR events; use RUST_LOG=repovec_core::systemd_units=trace when startup ordering or unit-contract diagnostics require the lower-level trace.

Concrete grepai indexer instances also start after and require both Qdrant and repovecd.