# systemd services

systemd is the Linux service manager that keeps Connect running. Two units matter. `connect` runs the web application under Uvicorn, and `connect-voice` runs the realtime voice worker. Both run as the unprivileged user `connect`, read the same environment file and restart within five seconds if they exit. PostgreSQL, Caddy and the mail server are units of their own.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/systemd/

## What it is

systemd is the init system and service manager used by most Linux distributions, including Ubuntu. It was started in 2010 by Lennart Poettering and Kay Sievers. A unit file declares how to start a service, what it depends on, how to restart it and which sandboxing to apply.

Its journal collects each service's output, so a start-up traceback is one `journalctl` command away.

**Category** — Service manager
**Units** — `connect`, `connect-voice`, plus PostgreSQL, Caddy and Stalwart
**Unit files** — `ops/aws/connect.service`, `ops/connect-voice.service`
**Official site** — [systemd.io](https://systemd.io/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `connect.service` | Uvicorn on 127.0.0.1:8420, after the network and PostgreSQL; `Restart=always` |
| `connect-voice.service` | `python -m backend.voice_worker.agent start`; graceful stop with SIGINT and a 210-second timeout so live calls can finish |
| Release scripts | Stop, swap the app directory, start, then probe health |

## How it connects

1. Boot: network-online, then PostgreSQL
2. `connect` starts and runs migrations before serving
3. `connect-voice` starts after `connect`
4. A crash triggers a restart five seconds later
5. A release restarts both units and the probes confirm health

## Benefits and limits

What it gives Connect:

- Automatic restart and ordered start-up without extra software.
- Sandboxing is declared next to the start command.
- The voice worker's long stop timeout means a release does not cut a call mid-sentence.

Where it stops, and what Connect does about it:

- Restart hides a crash loop unless someone reads the journal. The release probes check for a traceback after the restart for this reason.
- Units on one host are not high availability. If the host stops, both services stop.
- Environment-file changes need a restart to take effect.

## Security and privacy

- `User=connect`, `NoNewPrivileges=true` and `PrivateTmp=true` on both units.
- The voice worker adds `ProtectSystem=full`, `ProtectHome=true` and writes only to `/opt/connect/data`.
- The environment file holds the secrets. It lives on the host, never in the repository.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | LGPL-2.1-or-later (most of systemd) |
| Cost | None. It ships with Ubuntu |
| Version | Ubuntu 24.04's systemd |
| Compatibility | Any systemd-based Linux |

## Troubleshooting

**`connect` keeps restarting** — `journalctl -u connect -n 200`: a traceback at import or migration time is the usual cause.
**Calls drop during a release** — The voice unit was killed before its stop timeout. Check that the release used a graceful restart.
**A setting change has no effect** — The environment file is read at start. Restart the unit.

## Official references

- [systemd.service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html)
- [systemd.exec sandboxing](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html)
- [journalctl](https://www.freedesktop.org/software/systemd/man/latest/journalctl.html)

## Questions

### Why are web and voice separate services?

So a broken audio stack cannot stop mail from syncing, and a busy web request cannot delay an audio frame. They also have different stop needs: a call must be allowed to finish.

### Does a reboot start Connect automatically?

Yes. Both units are enabled for `multi-user.target`.

## Related

- [Uvicorn, the ASGI server](https://connectbyjbrh.com/docs/technology/uvicorn/)
- [LiveKit Agents and the voice worker](https://connectbyjbrh.com/docs/technology/livekit/)
- [Amazon Web Services hosting](https://connectbyjbrh.com/docs/technology/aws-hosting/)
- [Observability](https://connectbyjbrh.com/docs/technology/observability/)

## What this page is based on

- `ops/aws/connect.service`
- `ops/connect-voice.service`
- `docs/infrastructure/AWS-HOST.md`
