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

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.

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.

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.

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)

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.

👋 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.

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.

You can start using Ceryx in a few seconds!

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

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

docker-compose up -d

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. 

👋 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

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

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

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

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.

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

The Ceryx Web community project provides a sweet web UI

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.

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.

Ceryx is MIT licensed.