Quick start

In this guide you run Ceryx and a small sample service on your machine, then route echo.localhost to the service. All you need is Docker with Compose.

1. Run Ceryx#

docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:docs/compose.example.yml' up -d

This starts two containers in a Compose project named ceryx-example-echo: Ceryx, and echo, a service that answers every request with the same message.

2. Add a route#

The sample setup makes the API available on your machine at localhost:8080. Route echo.localhost to the echo service:

curl -X POST localhost:8080/api/routes \
  -H 'Content-Type: application/json' \
  -d '{"source": "echo.localhost", "target": "http://echo:5678"}'

Ceryx answers with the new route and its default settings:

{
  "source": "echo.localhost",
  "target": "http://echo:5678",
  "settings": {
    "enforce_https": false,
    "mode": "proxy",
    "certificate_path": null,
    "key_path": null,
    "mtls_require_client_certificate": false,
    "mtls_trusted_ca": null,
    "mtls_verify_depth": null
  }
}

3. Send a request#

curl http://echo.localhost

Hello from behind Ceryx

Hostnames ending in .localhost point to your own machine, so this works without setting up DNS. You can open http://echo.localhost in your browser too.

4. Clean up#

Stop the containers and remove their data:

docker compose -p ceryx-example-echo down -v

Next steps#

• Deploy to production to serve real domains over HTTPS.
• Local development to keep Ceryx running for your own projects.
• How routing works to see what Ceryx does with each request.