Ceryx - Rock-solid, programmable HTTP(S) reverse proxy

Ceryx is the rock-solid, programmable reverse proxy used to provide tens of thousands of SourceLair projects with their unique HTTPS-enabled public URLs.

High-level architecture

One of the main traits of Ceryx that makes it rock-solid is the simplicity in its design. Ceryx is comprised of two components and a Redis backend: the HTTP(S) reverse proxy and an API.

Proxy

Ceryx uses NGINX OpenResty under the hood to route requests, based on the HTTP request's Host header or the Server Name Indication in HTTPS requests. Ceryx queries the Redis backend to decide to which target it should route each request.

API

The Ceryx API lets users dynamically create, update and delete Ceryx routes via any HTTP client. The API essentially validates, sanitizes and eventually stores input in the Ceryx backend, to be queried by the proxy.

Configuration

Ceryx is configured with the following environment variables:

• CERYX_API_HOST: The host to bind the Ceryx API (default: 127.0.0.1)
• CERYX_API_HOSTNAME: Optional publicly accessible hostname for the Ceryx API (default: None)
• CERYX_API_PORT: The port to bind the Ceryx API (default: 5555)
• CERYX_DEBUG: Enable debug logs for Ceryx API (default: true)
• CERYX_DISABLE_LETS_ENCRYPT: Disable automatic Let's Encrypt HTTPS certificate generation (default: false)
• CERYX_DNS_RESOLVER: The IP of the DNS resolver to use (default: 127.0.0.11 — the Docker DNS resolver)
• CERYX_DOCKERIZE_EXTRA_ARGS: Extra arguments, to pass to dockerize (default: None)
• CERYX_MAX_REQUEST_BODY_SIZE: The maximum body size allowed for an incoming request to Ceryx (default: 100m — 100 megabytes)
• CERYX_REDIS_HOST: The Redis host to use as backend (default: 127.0.0.1)
• CERYX_REDIS_PASSWORD: Optional password to use for authenticating with Redis (default: None)
• CERYX_REDIS_PORT: The where Redis should be reached (default: 6379)
• CERYX_REDIS_PREFIX: The prefix to use in Ceryx-related Redis keys (default: ceryx)
• CERYX_REDIS_TIMEOUT: The timeout for all Redis operations, including the intial connection to Redis, specified in milliseconds (default: 100)
• CERYX_SSL_DEFAULT_CERTIFICATE: The path to the fallback SSL certificate (default: /etc/ceryx/ssl/default.crt — randomly generated at build time)
• CERYX_SSL_DEFAULT_KEY: The path to the fallback SSL certificate key (default: /etc/ceryx/ssl/default.key — randomly generated at build time)

Adjusting log level

Ceryx will output logs of level to equal or higher of info by default. Setting CERYX_DEBUG to true will also output logs of debug level.

Not running Ceryx as container?

👋 Heads up! Ceryx is designed to be run inside a container using Docker or similar tools.

If you're not running Ceryx using the official sourcelair/ceryx image, you'll need to take care of configuration file generation yourself. Take a look at entrypoint.sh to get ideas.

Dynamic SSL certificates

By default, Ceryx will try to generate a certificate when a domain is hit via HTTPS through Let's Encrypt, if and only if a route exists for it. To disable this behavior, set CERYX_DISABLE_LETS_ENCRYPT to true.

Quick start

You can start using Ceryx in a few seconds!

Requirements

Before getting started, make sure you have the following:

1. A computer accessible from the internet with Docker (docs) and Docker Compose (docs)
2. At least one domain (or subdomain) resolving to the computer's public IP addtess

Running Ceryx

Just run the following command to run Ceryx in the background:

docker-compose up -d

Running Ceryx in Kubernetes

Kubernetes Requirements

1. A Kubernetes cluster deployed with a public facing IP. Kubectl, Helm installed on your machine. Tiller installed on the cluster.

2. At least one domain/subdomain (or even a wildcard A record) resolving to the cluster IP address.

3. Edit the values file in .k8s/ceryx/values.yaml to suit your deployment needs.

cd k8s

helm install --debug --generate-name --values <path to your value file> ./ceryx

Recommend: Add --dry-run to the above before deploying to check generated yaml. 

Exposing the API to the public

👋 Heads up! Don't ever do this in production! Anyone from the internet will be able to access the Ceryx API and mess with it. It's useful for development/testing though.

To access (and therefore 🐶 dogfood) the Ceryx API via Ceryx' proxy, set the CERYX_API_HOSTNAME setting and run the following command in your terminal:

docker-compose exec api bin/populate-api

The Ceryx API

Add a new route to Ceryx

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"source":"publicly.accessible.domain","target":"http://service.internal:8000"}' \
     http://ceryx-api-host/api/routes

Update a route in Ceryx

curl -H "Content-Type: application/json" \
     -X PUT \
     -d '{"source":"publicly.accessible.domain","target":"http://another-service.internal:8000"}' \
     http://ceryx-api-host/api/routes/publicly.accessible.domain

Delete a route from Ceryx

curl -H "Content-Type: application/json" \
     -X DELETE \
     http://ceryx-api-host/api/routes/publicly.accessible.domain

Enforce HTTPS

You can enforce redirection from HTTP to HTTPS for any host you would like.

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"source":"publicly.accessible.domain","target":"http://service.internal:8000", "settings": {"enforce_https": true}}' \
     http://ceryx-api-host/api/routes

The above functionality works in PUT update requests as well.

Redirect to target, instead of proxying

Instead of proxying the request to the targetm you can prompt the client to redirect the request there itself.

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"source":"sourcelair.com","target":"https://www.sourcelair.com", "settings": {"mode": "redirect"}}' \
     http://ceryx-api-host/api/routes

Ceryx web UI

The Ceryx Web community project provides a sweet web UI

Real-world uses

Ceryx has proven to be extremely reliable in production systems, handling tens of thousands of routes in its backend. Some of them are:

• SourceLair: In-browser IDE for web applications, made publicly accessible via development web servers powered by Ceryx.
• Stolos: Managed Docker development environments for enterprises.

Do you use Ceryx in production as well? Please open a Pull Request to include it here. We would love to have it in our list.

Origin

Ceryx started in SourceLair to help provide tens of thousands of users with a unique public URL (subdomain) for each one of their projects. Initial development had different stages; from using tproxy, Twisted and bare NGINX as a proxy and backends ranging from MongoDB to etcd.

After a lot of experimentation, we have ended up in using OpenResty as the proxy and Redis as the backend. This solution has served us and we are now developing it in the open as an open source project.

License

Ceryx is MIT licensed.