Skip to content

getting-started.md

Latest commit

 

History

History
150 lines (109 loc) · 4.51 KB

getting-started.md

File metadata and controls

150 lines (109 loc) · 4.51 KB

Getting started with Chaperone

This tutorial walks you through running Chaperone and sending a proxied request. By the end, you'll see the proxy inject a credential into an outgoing request automatically.

Time: ~10 minutes

Prerequisites

Requirement Version Purpose
Docker 20.10+ Running Chaperone
curl any Sending test requests

Step 1: Build the Docker image

Clone the repository and build:

git clone https://github.com/cloudblue/chaperone.git
cd chaperone
docker build -t chaperone:latest .

Step 2: Start Chaperone

The repository includes tutorial configuration files in configs/:

What's in the tutorial config?

configs/getting-started.yaml defines the allow-list — which target hosts the proxy permits. For this tutorial, it allows httpbin.org (a public HTTP testing service):

server:
  addr: ":8443"
  admin_addr: ":9090"
  tls:
    enabled: false            # No mTLS for the tutorial

upstream:
  allow_list:
    "httpbin.org":
      - "/**"                 # Allow all paths on httpbin.org

configs/getting-started-credentials.json maps vendor IDs to credentials. The reference plugin reads this file and injects the configured header when a matching request arrives:

{
  "vendors": {
    "test-vendor": {
      "auth_type": "api_key",
      "header_name": "X-Injected-By",
      "token": "chaperone-tutorial"
    }
  }
}

In production, you'd replace these with real vendor hosts and enable TLS. See the Configuration Reference.

Start the container in the foreground so you can see the startup logs:

docker run --rm --name chaperone-tutorial \
  -p 8443:8443 \
  -p 9090:9090 \
  -v $(pwd)/configs/getting-started.yaml:/app/config.yaml:ro \
  -v $(pwd)/configs/getting-started-credentials.json:/app/credentials.json:ro \
  chaperone:latest -config /app/config.yaml -credentials /app/credentials.json

Chaperone logs are JSON-formatted. Look for these messages in the output:

  • "starting chaperone" — Startup with version and config summary
  • "loaded reference plugin" — Credentials file loaded
  • "admin server started" with addr=:9090 — Admin endpoints ready
  • "starting proxy server in HTTP mode (no mTLS) - FOR DEVELOPMENT ONLY" with addr=:8443 — Proxy accepting traffic (this is a warning because TLS is disabled — expected for the tutorial)
  • "server listening" — Ready for requests

Leave this terminal running and open a new terminal for the next steps.

Step 3: Verify health

Check that the proxy is running:

curl -s http://localhost:9090/_ops/health
{"status": "alive"}

The version endpoint is also available:

curl -s http://localhost:9090/_ops/version

Both endpoints are available on the admin port (9090) and the traffic port (8443).

Step 4: Send a proxied request

You tell Chaperone where to send a request using the X-Connect-Target-URL header, and which vendor's credentials to inject using X-Connect-Vendor-ID.

Send a request through the proxy to httpbin.org/headers, which echoes back all request headers it received:

curl -s http://localhost:8443/proxy \
  -H "X-Connect-Target-URL: https://httpbin.org/headers" \
  -H "X-Connect-Vendor-ID: test-vendor"

In the JSON response, look at the headers object. You'll see:

  • X-Injected-By: chaperone-tutorial — Chaperone's reference plugin looked up test-vendor in the credentials file and injected this header. The vendor received it; you didn't send it.
  • Connect-Request-Id — A trace ID generated by Chaperone for correlating logs across services.

Switch back to the terminal running Chaperone. The request log shows the trace ID, vendor ID, upstream status, and latency — but any sensitive header values are redacted.

Step 5: Clean up

Press Ctrl+C in the terminal running Chaperone to stop it.

Next steps

Now that you've seen Chaperone inject credentials into a proxied request: