chore(dev): route the dev stack through a shared Traefik instead of OrbStack

[suiramdev]

Summary

The development stack now reaches the browser through Traefik instead of OrbStack's built-in proxy. Each worktree is served at http://<service>.<slug>.freenary.localhost. Look at scripts/dev.ts › ensureProxy first, then at the labels and network aliases in docker-compose.dev.yml.

Motivation

• dev:up only gave a browsable stack under OrbStack. Docker Desktop, which another project on the same machine needs, has no equivalent.
• One Traefik on port 80, found on the external devproxy network, can serve every worktree and other projects that already share that network. No second proxy fights for the port.
• Plain HTTP on *.localhost needs no local CA. Chrome and Firefox treat it as a secure context.

Drawbacks

• Port 80 must be free, or held by a Traefik on devproxy.
• Safari does not treat *.localhost as a secure context.
• The stack depends on an external network. dev.ts creates it, but a bare docker compose -f docker-compose.dev.yml up fails when the network is missing.

Prior art

• OrbStack's dev.orbstack.domains labels. They were removed because they are runtime-specific.
• A Traefik per stack was rejected: stacks would conflict on port 80, and each proxy would route every stack's labels.
• Single-label hosts (web-<slug>.localhost) were rejected, because resolveCookiePolicy refuses a one-label cookie parent.

Notes

• Visual change: none. The stack is served at new addresses.
• Tests: scripts/dev-identity.test.ts now asserts the http and freenary.localhost host shapes.
• Docs updated: contributing/local-stack, contributing/index, contributing/writing-docs, and the generated self-hosting/configuration dev table.
• Review: the reviewer agent approved with no findings after two rounds. It found that bare server and mailpit names resolve across worktrees on devproxy, so the stack now uses the default-network aliases freenary-server and freenary-mailpit. It also found that the network must use the 172.30.0.0/16 subnet the sibling proxy expects.
• The self-hosting docker-compose.yml is untouched. There is no migration and no breaking change for operators.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 38c68a3a-13b6-4c48-aab2-2fd3d8be57a5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}