Linux systemd services

The checked-in unit files under deploy/systemd/ are templates for a default /opt/sentinel-secure-x installation. If your install root, Python path, or service account differ, render installation-specific unit files with the helper below instead of editing the tracked templates by hand.

Recommended flow

1. Install the application under your target root, for example /opt/sentinel-secure-x.
2. Create the virtual environment you want the services to use.
3. Copy .env.example to .env, set production values, and make sure PostgreSQL and any signing material are reachable from the service account.
4. Run the control-plane preflight against that .env file:

python3 -m server.preflight \
  --env-file /opt/sentinel-secure-x/.env \
  --services api worker maintenance scheduled-job-coordinator update-campaign-scheduler

1. Render and install the units:

sudo python3 deploy/systemd/install_services.py \
  --output-dir /etc/systemd/system \
  --install-root /opt/sentinel-secure-x \
  --python-executable /opt/sentinel-secure-x/.venv/bin/python \
  --user sentinel \
  --group sentinel \
  --env-file /opt/sentinel-secure-x/.env \
  --services api worker maintenance scheduled-job-coordinator update-campaign-scheduler \
  --reload-systemd \
  --enable \
  --start

1. Run the post-install smoke test:

python3 deploy/systemd/smoke_test_services.py \
  --services api worker maintenance scheduled-job-coordinator update-campaign-scheduler \
  --base-url http://127.0.0.1:8000

The helper waits for the selected units to become active and then checks /api/health/live plus /api/health/ready. If you expose readiness over HTTPS instead of the local Waitress listener, pass --base-url https://... and optionally --ca-file or --insecure.

1. Verify service status with systemctl status if needed, then confirm service heartbeats and background-service health from the control plane.

Notes

• The agent unit is available too, but most deployments run the agent on managed endpoints rather than the Linux control-plane host. Add agent to --services only when that is intentional.
• If you cannot use sudo, the installer also supports --user-mode and will render units under ~/.config/systemd/user by default. In that mode use systemctl --user daemon-reload, systemctl --user enable, systemctl --user start, and python3 deploy/systemd/smoke_test_services.py --user-mode.
• Prefer an install root and .env path without spaces for systemd-managed deployments. If your checkout path includes spaces, create a space-free symlink such as /home/<user>/sentinel-secure-x and deploy against that alias.
• The installer can run the same preflight automatically when you pass --env-file.
• The installer can also run the smoke test automatically when you add --smoke-test.
• Use --dry-run to preview rendered unit content without writing files.
• If you omit --reload-systemd, --enable, or --start, the helper prints the next systemctl commands to run manually.
• The unit templates still live in deploy/systemd/*.service; the helper only renders deployment-specific copies.