Quickstart & Examples
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a high-level overview and practical examples for getting started with kamal-proxy. It covers environment setup using Docker Compose, basic deployment commands, and common configuration patterns derived from the project's example implementations and CLI definitions.
The project operates as a high-performance proxy designed for the dash gem (a fork of Kamal). It handles TLS termination, request buffering, and dynamic service routing via a Unix socket RPC interface. Sources: CLAUDE.md:3-12, internal/cmd/run.go:139-160
Basic Environment Setup
The repository includes a pre-configured example environment to demonstrate the proxy's capabilities. This environment consists of the proxy itself and four instances of a simple Go-based upstream web server.
The diagram shows the request flow from a client through the proxy to a cluster of upstream web servers.
Sources: example/README.md:3-12, example/upstream/main.go:34-42
Launching the Example
To start the demonstration environment, navigate to the example directory and use Docker Compose:
docker compose up --build
Once the services are running, the proxy can be configured by executing commands within the proxy container. Accessing http://localhost/ initially will not route traffic until a service is deployed. Sources: example/README.md:7-12
Common Deployment Examples
Deploys are managed via the kamal-proxy deploy command, which communicates with the running proxy server via a Unix socket located at kamal-proxy.sock. Sources: CLAUDE.md:65-70, internal/cmd/deploy.go:189-195
Basic Service Deployment
Deploy a service named service1 pointing to a single target host:
docker compose exec proxy kamal-proxy deploy service1 --target example-web-1
Sources: example/README.md:14-16
Weighted Load Balancing
You can distribute traffic across multiple targets using weights. In this example, web-b receives five times more traffic than web-a:
kamal-proxy deploy my-app \
--target="web-a" \
--target="web-b;weight=5"
Sources: internal/cmd/deploy.go:40-42, ROADMAP.md:83
Path-Based Routing & Rewrites
Deploy a service that only responds to a specific path prefix and rewrites the internal path for an SPA:
kamal-proxy deploy frontend \
--target="web-1" \
--path-prefix="/app" \
--rewrite="/app/.*=/index.html"
Sources: internal/cmd/deploy.go:44-46,67-68, ROADMAP.md:95-97
Configuration Reference
Deployment Options
Key flags for the deploy command allow fine-grained control over service behavior, including security and performance tuning.
| Flag | Type | Description |
|---|---|---|
--target | StringSlice | Target host(s) as <host>[:<port>][;weight=<n>]. |
--tls | Boolean | Enables TLS (requires a non-empty host). |
--basic-auth | String | Sets <user>:<pass> for the service. Credentials are hashed CLI-side. |
--compress | StringSlice | Enables compression (gzip, br, zstd). |
--cache | Boolean | Enables response caching based on target headers. |
--target-timeout | Duration | Max time to wait for target server response (default 10s). |
Sources: internal/cmd/deploy.go:39-125, ROADMAP.md:58,63,68,75,100,105
Server Runtime Options
The run command initializes the proxy server and configures global settings.
Sequence of internal operations when a deployment command is issued to a running server.
Sources: CLAUDE.md:65-70, internal/cmd/run.go:142-180
| Flag | Default | Description |
|---|---|---|
--http-port | 80 | Port for HTTP traffic. |
--https-port | 443 | Port for HTTPS traffic. |
--log-format | text | Log output format (json or text). |
--data-dir | ~/.config/kamal-proxy | Directory for state and certificate storage. |
--acme-email | (None) | Email for ACME account registration. |
Sources: internal/cmd/run.go:34-60
Summary
kamal-proxy provides a robust, CLI-driven interface for managing containerized web services. By utilizing the provided example environment, developers can quickly test load balancing, TLS provisioning, and traffic shaping features like path rewrites and compression. The architecture relies on a persistent server process that maintains state across restarts, ensuring routing and certificates remain consistent. Sources: CLAUDE.md:72-75, internal/cmd/run.go:150-155