Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/withlogicco/ceryx
Dynamic reverse proxy based on NGINX OpenResty with an API
https://github.com/withlogicco/ceryx
docker lets-encrypt letsencrypt nginx nginx-openresty proxy ssl
Last synced: about 2 months ago
JSON representation
Dynamic reverse proxy based on NGINX OpenResty with an API
- Host: GitHub
- URL: https://github.com/withlogicco/ceryx
- Owner: withlogicco
- License: mit
- Created: 2015-06-23T07:48:03.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-03-27T21:54:05.000Z (over 1 year ago)
- Last Synced: 2024-04-11T21:18:22.460Z (5 months ago)
- Topics: docker, lets-encrypt, letsencrypt, nginx, nginx-openresty, proxy, ssl
- Language: Python
- Homepage:
- Size: 235 KB
- Stars: 759
- Watchers: 49
- Forks: 146
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - withlogicco/ceryx - Dynamic reverse proxy based on NGINX OpenResty with an API (docker)
README
# Ceryx - Rock-solid, programmable HTTP(S) reverse proxy
[](https://travis-ci.org/sourcelair/ceryx)
Ceryx is the rock-solid, programmable reverse proxy used to provide tens of thousands of [SourceLair](https://www.sourcelair.com/) 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](https://en.wikipedia.org/wiki/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`](https://hub.docker.com/r/sourcelair/ceryx/) image, you'll need to take care of configuration file generation yourself. Take a look at [`entrypoint.sh`](ceryx/bin/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](https://docs.docker.com/install/linux/docker-ce/ubuntu/)) and Docker Compose ([docs](https://docs.docker.com/compose/install/))
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.
4.
```
cd k8s
helm install --debug --generate-name --values ./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](https://github.com/parisk/ceryx-web) 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**](https://www.sourcelair.com/): In-browser IDE for web applications, made publicly accessible via development web servers powered by Ceryx.
- [**Stolos**](http://stolos.io/): Managed Docker development environments for enterprises.
Do you use Ceryx in production as well? Please [open a Pull Request](https://github.com/sourcelair/ceryx/pulls) to include it here. We would love to have it in our list.
## Origin
Ceryx started in [SourceLair](https://www.sourcelair.com) 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](https://github.com/benoitc/tproxy), [Twisted](https://www.twistedmatrix.com/trac/) and bare [NGINX](https://nginx.org/en/) as a proxy and backends ranging from [MongoDB](https://www.mongodb.com/) to [etcd](https://github.com/etcd-io/etcd).
After a lot of experimentation, we have ended up in using [OpenResty](https://openresty.org/en/) as the proxy and [Redis](https://redis.io/) 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](LICENSE).