Uvicorn, the ASGI server
Uvicorn is the server process that runs Connect's web application. systemd starts it as the connect service, listening only on 127.0.0.1:8420. Caddy forwards public traffic to it. Uvicorn turns each HTTP connection into ASGI calls that FastAPI answers, and trusts proxy headers only from the local Caddy.
What it is#
Uvicorn is an ASGI web server for Python from the Encode project. ASGI is the asynchronous successor to WSGI: one interface for HTTP requests, server-sent events and WebSockets that frameworks such as Starlette and FastAPI implement.
The [standard] extra that Connect installs adds faster optional components where the platform supports them: the uvloop event loop, the httptools parser, WebSocket support and file watching for development reloads.
- Category
- ASGI web server
- Version in Connect
uvicorn[standard]>=0.30- How it is started
uvicorn backend.app.main:app --host 127.0.0.1 --port 8420 --proxy-headers --forwarded-allow-ips 127.0.0.1- Official site
- uvicorn.dev
Where Connect uses it#
| Place in Connect | What it does there |
|---|---|
ops/aws/connect.service | The production command line, run as user connect |
| Local development | The same app with reload on, against a _test database (AGENTS.md §5) |
tools/ui_gate.py and the browser suites | Boot this checkout under Uvicorn to look at real screens |
How it connects#
- systemd starts Uvicorn from
/opt/connect/venv - Uvicorn binds to the loopback interface only
- Caddy terminates TLS and proxies to port 8420
- Uvicorn reads
X-Forwarded-ForandX-Forwarded-Proto, but only from127.0.0.1 - The ASGI app (FastAPI) handles the request
Benefits and limits#
What it gives Connect:
- Small and fast, with streaming responses, which Connect's server-sent event stream needs.
- Binding to loopback means the application is unreachable except through Caddy.
- Restarts are cheap. systemd restarts it in five seconds if it exits.
Where it stops, and what Connect does about it:
- One worker process. CPU-bound work in a request competes with every other request, which is why heavy jobs run elsewhere.
- Proxy-header trust is all or nothing per source address. If it were widened beyond
127.0.0.1, any client could claim any IP. - A restart drops open streams. The browser's event stream reconnects by itself.
Security and privacy#
--forwarded-allow-ips 127.0.0.1stops a client from forging its own address or scheme.- The service runs with
NoNewPrivileges=trueandPrivateTmp=true. - No public port: the host's firewall opens nothing for 8420, and the cloud security group opens no inbound port at all for management.
Licence, cost and versions#
| Question | Answer |
|---|---|
| Licence | BSD-3-Clause |
| Cost | None |
| Version | uvicorn[standard]>=0.30 (a floor) |
| Compatibility | ASGI 3, Python 3.12, FastAPI/Starlette |
Troubleshooting#
- 502 from Caddy
- Uvicorn is not answering on 8420. Check
systemctl status connectand the journal for a start-up traceback. - Every request seems to come from 127.0.0.1
- Proxy headers are not being read. The service's
--proxy-headersflag is missing. - Slow first request after a release
- Boot runs schema migrations before serving. The release script's probes wait for readiness.
Official references#
Questions#
Why not Gunicorn with several workers?
Connect keeps per-process locks and caches. The work that would need more cores, the realtime voice, already runs as its own service. One Uvicorn process behind Caddy is the measured shape on the current host.
Can Uvicorn be reached directly from the internet?
No. It listens on 127.0.0.1 only, and the only public listener on the host is Caddy.