{"id":13557270,"url":"https://github.com/withlogicco/ceryx","last_synced_at":"2025-04-12T19:43:40.774Z","repository":{"id":50124290,"uuid":"37904786","full_name":"withlogicco/ceryx","owner":"withlogicco","description":"Dynamic reverse proxy based on NGINX OpenResty with an API","archived":false,"fork":false,"pushed_at":"2023-03-27T21:54:05.000Z","size":241,"stargazers_count":788,"open_issues_count":15,"forks_count":145,"subscribers_count":50,"default_branch":"master","last_synced_at":"2024-08-09T23:01:54.372Z","etag":null,"topics":["docker","lets-encrypt","letsencrypt","nginx","nginx-openresty","proxy","ssl"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/withlogicco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-06-23T07:48:03.000Z","updated_at":"2024-08-04T15:37:35.000Z","dependencies_parsed_at":"2024-01-14T16:07:54.262Z","dependency_job_id":"c3dd6fbb-71c3-4bdf-be4b-3a10f7aad6b8","html_url":"https://github.com/withlogicco/ceryx","commit_stats":null,"previous_names":["sourcelair/ceryx"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withlogicco%2Fceryx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withlogicco%2Fceryx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withlogicco%2Fceryx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withlogicco%2Fceryx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/withlogicco","download_url":"https://codeload.github.com/withlogicco/ceryx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625479,"owners_count":21135512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","lets-encrypt","letsencrypt","nginx","nginx-openresty","proxy","ssl"],"created_at":"2024-08-01T12:04:15.044Z","updated_at":"2025-04-12T19:43:40.565Z","avatar_url":"https://github.com/withlogicco.png","language":"Python","readme":"# Ceryx - Rock-solid, programmable HTTP(S) reverse proxy\n\n[![Build Status](https://travis-ci.org/sourcelair/ceryx.svg)](https://travis-ci.org/sourcelair/ceryx)\n\nCeryx 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.\n\n## High-level architecture\n\nOne 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.\n\n### Proxy\nCeryx 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.\n\n### API\nThe 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.\n\n## Configuration\n\nCeryx is configured with the following environment variables:\n\n  - `CERYX_API_HOST`: The host to bind the Ceryx API (default: `127.0.0.1`)\n  - `CERYX_API_HOSTNAME`: Optional publicly accessible hostname for the Ceryx API (default: None)\n  - `CERYX_API_PORT`: The port to bind the Ceryx API (default: `5555`)\n  - `CERYX_DEBUG`: Enable debug logs for Ceryx API (default: `true`)\n  - `CERYX_DISABLE_LETS_ENCRYPT`: Disable automatic Let's Encrypt HTTPS certificate generation (default: `false`)\n  - `CERYX_DNS_RESOLVER`: The IP of the DNS resolver to use (default: `127.0.0.11` — the Docker DNS resolver)\n  - `CERYX_DOCKERIZE_EXTRA_ARGS`: Extra arguments, to pass to `dockerize` (default: None)\n  - `CERYX_MAX_REQUEST_BODY_SIZE`: The maximum body size allowed for an incoming request to Ceryx (default: `100m` — 100 megabytes)\n  - `CERYX_REDIS_HOST`: The Redis host to use as backend (default: `127.0.0.1`)\n  - `CERYX_REDIS_PASSWORD`: Optional password to use for authenticating with Redis (default: None)\n  - `CERYX_REDIS_PORT`: The where Redis should be reached (default: `6379`)\n  - `CERYX_REDIS_PREFIX`: The prefix to use in Ceryx-related Redis keys (default: `ceryx`)\n  - `CERYX_REDIS_TIMEOUT`: The timeout for all Redis operations, including the intial connection to Redis, specified in milliseconds (default: `100`)\n  - `CERYX_SSL_DEFAULT_CERTIFICATE`: The path to the fallback SSL certificate (default: `/etc/ceryx/ssl/default.crt` — randomly generated at build time)\n  - `CERYX_SSL_DEFAULT_KEY`: The path to the fallback SSL certificate key (default: `/etc/ceryx/ssl/default.key` — randomly generated at build time)\n\n## Adjusting log level\n\nCeryx 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.\n\n### Not running Ceryx as container?\n\n👋 **Heads up!** Ceryx is designed to be run inside a container using Docker or similar tools. \n\nIf 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.\n\n### Dynamic SSL certificates\n\nBy 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`.\n\n## Quick start\n\nYou can start using Ceryx in a few seconds!\n\n### Requirements\n\nBefore getting started, make sure you have the following:\n\n1. 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/))\n2. At least one domain (or subdomain) resolving to the computer's public IP addtess\n\n### Running Ceryx\n\nJust run the following command to run Ceryx in the background:\n\n```\ndocker-compose up -d\n```\n\n### Running Ceryx in Kubernetes ###\n\n#### Kubernetes Requirements ####\n1. A Kubernetes cluster deployed with a public facing IP. Kubectl, Helm installed on your machine. Tiller installed on the cluster.  \n\n2. At least one domain/subdomain (or even a wildcard A record) resolving to the cluster IP address.  \n\n3. Edit the values file in .k8s/ceryx/values.yaml to suit your deployment needs.\n\n4. \n```\ncd k8s\n\nhelm install --debug --generate-name --values \u003cpath to your value file\u003e ./ceryx\n\nRecommend: Add --dry-run to the above before deploying to check generated yaml. \n\n```\n\n### Exposing the API to the public\n\n**👋 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.\n\nTo access (and therefore 🐶 dogfood) the Ceryx API via Ceryx' proxy, set the `CERYX_API_HOSTNAME` setting and run the following command in your terminal:\n\n```\ndocker-compose exec api bin/populate-api\n```\n\n## The Ceryx API\n\n### Add a new route to Ceryx\n\n```\ncurl -H \"Content-Type: application/json\" \\\n     -X POST \\\n     -d '{\"source\":\"publicly.accessible.domain\",\"target\":\"http://service.internal:8000\"}' \\\n     http://ceryx-api-host/api/routes\n```\n\n### Update a route in Ceryx\n\n```\ncurl -H \"Content-Type: application/json\" \\\n     -X PUT \\\n     -d '{\"source\":\"publicly.accessible.domain\",\"target\":\"http://another-service.internal:8000\"}' \\\n     http://ceryx-api-host/api/routes/publicly.accessible.domain\n```\n\n### Delete a route from Ceryx\n\n```\ncurl -H \"Content-Type: application/json\" \\\n     -X DELETE \\\n     http://ceryx-api-host/api/routes/publicly.accessible.domain\n```\n\n### Enforce HTTPS\n\nYou can enforce redirection from HTTP to HTTPS for any host you would like.\n\n```\ncurl -H \"Content-Type: application/json\" \\\n     -X POST \\\n     -d '{\"source\":\"publicly.accessible.domain\",\"target\":\"http://service.internal:8000\", \"settings\": {\"enforce_https\": true}}' \\\n     http://ceryx-api-host/api/routes\n```\n\nThe above functionality works in `PUT` update requests as well.\n\n### Redirect to target, instead of proxying\n\nInstead of proxying the request to the targetm you can prompt the client to redirect the request there itself.\n\n```\ncurl -H \"Content-Type: application/json\" \\\n     -X POST \\\n     -d '{\"source\":\"sourcelair.com\",\"target\":\"https://www.sourcelair.com\", \"settings\": {\"mode\": \"redirect\"}}' \\\n     http://ceryx-api-host/api/routes\n```\n\n## Ceryx web UI\n\nThe [Ceryx Web community project](https://github.com/parisk/ceryx-web) provides a sweet web UI \n\n## Real-world uses\n\nCeryx has proven to be extremely reliable in production systems, handling tens of thousands of routes in its backend. Some of them are:\n\n- [**SourceLair**](https://www.sourcelair.com/): In-browser IDE for web applications, made publicly accessible via development web servers powered by Ceryx.\n- [**Stolos**](http://stolos.io/): Managed Docker development environments for enterprises.\n\nDo 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.\n\n## Origin\n\nCeryx 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).\n\nAfter 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.\n\n## License\n\nCeryx is [MIT licensed](LICENSE).\n","funding_links":[],"categories":["Python","docker"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithlogicco%2Fceryx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwithlogicco%2Fceryx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithlogicco%2Fceryx/lists"}