Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: add Caddy subdomain routing pattern (#676)
Maximilian Roos01b2b8bf8d71
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.mdindex 4ddf544c5..9210ab308 100644--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md@@ -52,13 +52,6 @@ The URL column in `wt list` shows each worktree's dev server:Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.-For subdomain-based routing (useful for cookies and CORS), use `lvh.me` which resolves to 127.0.0.1:--```toml-[post-start]-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"-```-## Database per worktreeEach worktree can have its own isolated database. Docker containers get unique names and ports:@@ -248,6 +241,41 @@ To create a worktree and immediately attach:wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'```+## Subdomain routing with Caddy+<!-- Hand-tested 2025-01-15 -->++Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.++**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)++```toml+# .config/wt.toml+[post-start]+server = "npm run dev -- --port {{ branch | hash_port }}"+proxy = """+ curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start+ curl -sf http://localhost:2019/config/apps/http/servers/wt || \+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \+ -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'+ curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.lvh.me"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}'+"""++[pre-remove]+proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true"++[list]+url = "http://{{ branch | sanitize }}.{{ repo }}.lvh.me:8080"+```++**How it works:**++1. `wt switch --create feature-auth` runs the `post-start` hook, starting the dev server on a deterministic port (`{{ branch | hash_port }}` → 16460)+2. The hook starts Caddy if needed and registers a route using the same port: `feature-auth.myproject` → `localhost:16460`+3. `lvh.me` is a public domain with wildcard DNS — `*.lvh.me` resolves to `127.0.0.1`+4. Visiting `http://feature-auth.myproject.lvh.me:8080`: Caddy matches the subdomain and proxies to the dev server+## Bare repository layoutAn alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex fba3f89d9..6fd6e0e5b 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -64,13 +64,6 @@ The URL column in `wt list` shows each worktree's dev server:Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.-For subdomain-based routing (useful for cookies and CORS), use `lvh.me` which resolves to 127.0.0.1:--```toml-[post-start]-server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"-```-## Database per worktreeEach worktree can have its own isolated database. Docker containers get unique names and ports:@@ -260,6 +253,41 @@ To create a worktree and immediately attach:wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'```+## Subdomain routing with Caddy+<!-- Hand-tested 2025-01-15 -->++Clean URLs like `http://feature-auth.myproject.lvh.me` without port numbers. Useful for cookies, CORS, and matching production URL structure.++**Prerequisites:** [Caddy](https://caddyserver.com/docs/install) (`brew install caddy`)++```toml+# .config/wt.toml+[post-start]+server = "npm run dev -- --port {{ branch | hash_port }}"+proxy = """+ curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start+ curl -sf http://localhost:2019/config/apps/http/servers/wt || \+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \+ -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}'+ curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true+ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \+ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.lvh.me"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}'+"""++[pre-remove]+proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true"++[list]+url = "http://{{ branch | sanitize }}.{{ repo }}.lvh.me:8080"+```++**How it works:**++1. `wt switch --create feature-auth` runs the `post-start` hook, starting the dev server on a deterministic port (`{{ branch | hash_port }}` → 16460)+2. The hook starts Caddy if needed and registers a route using the same port: `feature-auth.myproject` → `localhost:16460`+3. `lvh.me` is a public domain with wildcard DNS — `*.lvh.me` resolves to `127.0.0.1`+4. Visiting `http://feature-auth.myproject.lvh.me:8080`: Caddy matches the subdomain and proxies to the dev server+## Bare repository layoutAn alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: