Ceryx logo
Menu
View as Markdown

Routing

What Ceryx does with a request, from the moment it arrives until it reaches your service.

The life of a request

  1. Ceryx reads the hostname from the request's Host header. For HTTPS, the TLS handshake comes first, and Ceryx picks the certificate for the hostname the client asked for.
  2. It finds the route for that hostname. Hostnames match exactly: a route for example.com doesn't serve www.example.com. Without an exact match, Ceryx uses the catch-all route, whose source is $wildcard. Without either, it answers 503 Service Unavailable.
  3. It applies the route's settings. If the request is plain HTTP and the route has enforce_https, Ceryx redirects it to HTTPS. If the route requires client certificates, Ceryx checks the client's certificate. See API protection with mTLS.
  4. It proxies or redirects the request to the route's target, depending on the route's mode.

Targets

A target is the URL of a service, such as http://app:8000. Ceryx adds the request's path and query string to it:

Target Request Goes to
http://app:8000 https://example.com/users?page=2 http://app:8000/users?page=2
http://app:8000/v2 https://example.com/users http://app:8000/v2/users
app:8000 https://example.com/ http://app:8000/

A target without a scheme gets http://, and a trailing slash is dropped. Hostnames in targets are resolved with Docker's DNS, so containers on the ceryx network are reachable by name. Set CERYX_DNS_RESOLVER to use another DNS server.

Proxy and redirect modes

In proxy mode, the default, Ceryx forwards the request to the target and returns the response. It forwards the original Host header and adds X-Forwarded-For, X-Real-IP and X-Forwarded-Proto. WebSocket upgrades pass through, and clients can use HTTP/2 over HTTPS.

In redirect mode, Ceryx answers with a permanent redirect (301) to the target, with the request's path and query string added. Use it to move visitors from one domain to another, for example from www.example.com to example.com.

Where routes live

Routes are stored in a SQLite database in the /var/lib/ceryx volume, together with certificates. Ceryx caches route lookups in memory for a few seconds. Changes made through the API clear the cache, so they apply to the very next request, with no reload. Hostnames served by the catch-all route can briefly keep its previous target after you change it. See Architecture.

Errors

Status Cause
503 Service Unavailable No route for the hostname, and no catch-all route.
502 Bad Gateway Ceryx found the route but couldn't reach the target. Check that the service is running, and on the ceryx network if it's a container.
413 Content Too Large The request body is larger than CERYX_MAX_REQUEST_BODY_SIZE.
403 Forbidden and 421 Misdirected Request The route requires client certificates. See API protection with mTLS.
Esc

Type to search the docs.