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.
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
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#
- Boot: network-online, then PostgreSQL
connectstarts and runs migrations before servingconnect-voicestarts afterconnect- A crash triggers a restart five seconds later
- 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=trueandPrivateTmp=trueon both units.- The voice worker adds
ProtectSystem=full,ProtectHome=trueand 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#
connectkeeps restartingjournalctl -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#
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.