Ceryx - Simple, but powerful Reverse Proxy
Ceryx is a dynamic reverse proxy based on NGINX OpenResty with an API.
Ceryx is used to provide public URLs to tens of thousands of projects at https://www.sourcelair.com.
Proxy
Ceryx is using NGINX OpenResty under the hood, in order to route requests based on the request host. The routing is made using the NGINX Lua module, which is querying a Redis backend for results.
API
Ceryx comes with a simple Flask web service, which supports REST operations on routes. You can dynamically create, update, and delete routes on the go using a REST client.
Configuration
Ceryx supports configuration using environment variables. The supported configuration options are the following:
CERYX_API_HOST
: sets the host that the API will bind to - defaults to 127.0.0.1CERYX_API_HOSTNAME
: identical toCERYX_SERVER_NAME
, but without imposingHost
header limits - default to NoneCERYX_API_PORT
: sets the port that the API will listen - defaults to 5555CERYX_DEBUG
: enables debugging on the API service - defaults to trueCERYX_DISABLE_LETS_ENCRYPT
: if true, the automatic generation through Let's Encrypt does not kick in, defaults to falseCERYX_DNS_RESOLVER
: the IP of the DNS resolver to use, defaults to 127.0.0.11 — the Docker DNS resolverCERYX_DOCKERIZE_EXTRA_ARGS
: extra arguments, to pass todockerize
CERYX_NAME
: sets the API service name - defaults to ceryxCERYX_REDIS_HOST
: the redis host to connect to - defaults to 127.0.0.1CERYX_REDIS_PASSWORD
: the redis password to use - defaults to noneCERYX_REDIS_PORT
: the redis port to connect to - defaults to 6379CERYX_REDIS_PREFIX
: the redis prefix to use in keys - defaults to ceryxCERYX_SECRET_KEY
: the path of the secret key to use - defaults to NoneCERYX_SERVER_NAME
: the URL of the API service - default to NoneCERYX_SSL_CERT_KEY
: the path to the SSL certificate key to use as fallback, defaults to a randomly generated keyCERYX_SSL_CERT
: the path to the SSL certificate to use as fallback, defaults to a randomly generated certificate
If you're not using the sourcelair/ceryx
image, you'll need to use a command similar to the one below, to generate the configuration files needed from the environment, using dockerize
, through the entrypoint.sh
script.
bash ceryx/nginx/entrypoint.sh /usr/local/openresty/bin/openresty -g "daemon off;"
Quick Bootstrap
Ceryx loves Docker, so you can easily bootstrap Ceryx using the following command, given that you have already installed Docker and Docker Compose.
docker-compose up
To access (and therefore 🐶 dogfood 🐶) the Ceryx API via Ceryx' proxy, set the
CERYX_API_HOSTNAME
environment variable and run the following command in your terminal:
docker-compose exec api bin/populate-api
Development
Ceryx was developed as a private project for SourceLair PC. Initial development had different stages, having tproxy, Twisted and plain NGINX as a proxy server and backends ranging from MongoDB to etcd.
After a lot of experimentation, we have ended up in this solution and we'll keep developing this as an Open Source project. Feel free to make suggestions in the issues section in Github or open o pull request.
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. If you don't want this to be enabled, you can use the CERYX_DISABLE_LETS_ENCRYPT
setting.
License
Ceryx is licensed under the "The MIT License (MIT)".
The MIT License (MIT)
Copyright (c) 2015 SourceLair PC
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.