{"id":15666950,"url":"https://github.com/basecamp/kamal-proxy","last_synced_at":"2025-07-20T03:31:14.779Z","repository":{"id":257448402,"uuid":"775483657","full_name":"basecamp/kamal-proxy","owner":"basecamp","description":"Lightweight proxy server for Kamal","archived":false,"fork":false,"pushed_at":"2025-07-10T16:39:15.000Z","size":421,"stargazers_count":902,"open_issues_count":2,"forks_count":46,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-07-18T05:34:46.951Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://kamal-deploy.org/","language":"Go","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/basecamp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-21T13:28:41.000Z","updated_at":"2025-07-17T17:57:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"f2cc9bbf-9c37-4e7c-b2fe-ee74e586d01f","html_url":"https://github.com/basecamp/kamal-proxy","commit_stats":null,"previous_names":["basecamp/kamal-proxy"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/basecamp/kamal-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fkamal-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fkamal-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fkamal-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fkamal-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basecamp","download_url":"https://codeload.github.com/basecamp/kamal-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fkamal-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266063095,"owners_count":23870716,"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":[],"created_at":"2024-10-03T14:01:27.876Z","updated_at":"2025-07-20T03:31:14.773Z","avatar_url":"https://github.com/basecamp.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"# Kamal Proxy - A minimal HTTP proxy for zero-downtime deployments\n\n\n## What it does\n\nKamal Proxy is a tiny HTTP proxy, designed to make it easy to coordinate\nzero-downtime deployments. By running your web applications behind Kamal Proxy,\nyou can deploy changes to them without interrupting any of the traffic that's in\nprogress. No particular cooperation from an application is required for this to\nwork.\n\nKamal Proxy is designed to work as part of [Kamal](https://kamal-deploy.org/),\nwhich provides a complete deployment experience including container packaging\nand provisioning. However, Kamal Proxy could also be used standalone or as part\nof other deployment tooling.\n\n\n## A quick overview\n\nTo run an instance of the proxy, use the `kamal-proxy run` command. There's no\nconfiguration file, but there are some options you can specify if the defaults\naren't right for your application.\n\nFor example, to run the proxy on a port other than 80 (the default) you could:\n\n    kamal-proxy run --http-port 8080\n\nRun `kamal-proxy help run` to see the full list of options.\n\nTo route traffic through the proxy to a web application, you `deploy` instances\nof the application to the proxy. Deploying an instance makes it available to the\nproxy, and replaces the instance it was using before (if any).\n\nUse the format `hostname:port` when specifying the instance to deploy.\n\nFor example:\n\n    kamal-proxy deploy service1 --target web-1:3000\n\nThis will instruct the proxy to register `web-1:3000` to receive traffic under\nthe service name `service1`. It will immediately begin running HTTP health\nchecks to ensure it's reachable and working and, as soon as those health checks\nsucceed, will start routing traffic to it.\n\nIf the instance fails to become healthy within a reasonable time, the `deploy`\ncommand will stop the deployment and return a non-zero exit code, allowing\ndeployment scripts to handle the failure appropriately.\n\nEach deployment takes over all the traffic from the previously deployed\ninstance. As soon as Kamal Proxy determines that the new instance is healthy,\nit will route all new traffic to that instance.\n\nThe `deploy` command also waits for traffic to drain from the old instance before\nreturning. This means it's safe to remove the old instance as soon as `deploy`\nreturns successfully, without interrupting any in-flight requests.\n\nBecause traffic is only routed to a new instance once it's healthy, and traffic\nis drained completely from old instances before they are removed, deployments\ntake place with zero downtime.\n\n### Customizing the health check\n\nBy default, Kamal Proxy will test the health of each service by sending a `GET`\nrequest to `/up`, once per second. A `200` response is considered healthy.\n\nIf you need to customize the health checks for your application, there are a\nfew `deploy` flags you can use. See the help for `--health-check-path`,\n`--health-check-timeout`, and `--health-check-interval`.\n\nFor example, to change the health check path to something other than `/up`, you\ncould:\n\n    kamal-proxy deploy service1 --target web-1:3000 --health-check-path web/index.html\n\n### Host-based routing\n\nHost-based routing allows you to run multiple applications on the same server,\nusing a single instance of Kamal Proxy to route traffic to all of them.\n\nWhen deploying an instance, you can specify a host that it should serve traffic\nfor:\n\n    kamal-proxy deploy service1 --target web-1:3000 --host app1.example.com\n\nWhen deployed in this way, the instance will only receive traffic for the\nspecified host. By deploying multiple instances, each with their own host, you\ncan run multiple applications on the same server without port conflicts.\n\nOnly one service at a time can route a specific host:\n\n    kamal-proxy deploy service1 --target web-1:3000 --host app1.example.com\n    kamal-proxy deploy service2 --target web-2:3000 --host app1.example.com # returns \"Error: host is used by another service\"\n    kamal-proxy remove service1\n    kamal-proxy deploy service2 --target web-2:3000 --host app1.example.com # succeeds\n\n\n### Path-based routing\n\nFor applications that split their traffic to different services based on the\nrequest path, you can use path-based routing to mount services under different\npath prefixes.\n\nFor example, to send all the requests for paths begining with `/api` to web-1,\nand the rest to web-2:\n\n    kamal-proxy deploy service1 --target web-1:3000 --path-prefix=/api\n    kamal-proxy deploy service2 --target web-2:3000\n\nBy default, the path prefix will be stripped from the request before it is\nforwarded upstream. So in the example above, a request to `/api/users/123` will\nbe forwarded to `web-1` as `/users/123`. To instead forward the request with\nthe original path (including the prefix), specify `--strip-path-prefix=false`:\n\n    kamal-proxy deploy service1 --target web-1:3000 --path-prefix=/api --strip-path-prefix=false\n\n\n### Automatic TLS\n\nKamal Proxy can automatically obtain and renew TLS certificates for your\napplications. To enable this, add the `--tls` flag when deploying an instance:\n\n    kamal-proxy deploy service1 --target web-1:3000 --host app1.example.com --tls\n\nAutomatic TLS requires that hosts are specified (to ensure that certificates\nare not maliciously requests for arbitrary hostnames).\n\nAdditionally, when using path-based routing, TLS options must be set on the\nroot path. Services deployed to other paths on the same host will use the same\nTLS settings as those specified for the root path.\n\n\n### Custom TLS certificate\n\nWhen you obtained your TLS certificate manually, manage your own certificate authority,\nor need to install Cloudflare origin certificate, you can manually specify path to\nyour certificate file and the corresponding private key:\n\n    kamal-proxy deploy service1 --target web-1:3000 --host app1.example.com --tls --tls-certificate-path cert.pem --tls-private-key-path key.pem\n\n\n## Specifying `run` options with environment variables\n\nIn some environments, like when running a Docker container, it can be convenient\nto specify `run` options using environment variables. This avoids having to\nupdate the `CMD` in the Dockerfile to change the options. To support this,\n`kamal-proxy run` will read each of its options from environment variables if they\nare set. For example, setting the HTTP port can be done with either:\n\n    kamal-proxy run --http-port 8080\n\nor:\n\n    HTTP_PORT=8080 kamal-proxy run\n\nIf any of the environment variables conflict with something else in your\nenvironment, you can prefix them with `KAMAL_PROXY_` to disambiguate them. For\nexample:\n\n    KAMAL_PROXY_HTTP_PORT=8080 kamal-proxy run\n\n\n## Building\n\nTo build Kamal Proxy locally, if you have a working Go environment you can:\n\n    make\n\nAlternatively, build as a Docker container:\n\n    make docker\n\n\n## Trying it out\n\nSee the [example](./example) folder for a Docker Compose setup that you can use\nto try out the proxy commands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fkamal-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasecamp%2Fkamal-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fkamal-proxy/lists"}