2. A local environment with orca and Traefik


The application is going to be split across a few repositories: an API, a UI (the app plus a marketing website), this blog, an infra repo, and a small repo that holds the shared local environment. That’s the right shape for the project, but it makes local development annoying unless I do something about it. I don’t want to open five terminals, remember five sets of ports, and fight CORS between localhost:3000 and localhost:8080.

What I want is:

  • One command to start everything, and one to stop it.
  • Real hostnames, over HTTPS, that look like production: app.devflo.test, api.devflo.test, blog.devflo.test.
  • Each repo keeps a completely normal docker-compose.yml, so it still works without any special tooling.
  • Anything I (or an AI coding agent) run for a project runs inside its container, not on my laptop.

This post is how I ended up with that.

The pieces

graph LR
    Browser -->|https://api.devflo.test| T
    Browser -->|https://app.devflo.test| T
    Browser -->|https://blog.devflo.test| T

    subgraph Docker
        T[Traefik]
        T --> API[api]
        T --> APP[ui / app]
        T --> WEB[ui / website]
        T --> BLOG[blog / astro]
    end

Every project is its own docker compose project, but they all join one shared network, and a single Traefik container in front terminates TLS and routes by hostname. The glue that makes several compose projects behave like one environment is orca.

Orca

Orca manages a workspace made of several projects, each one a repository with a compose file. The workspace is described in a file that lives in the local-env repo:

# local-env/orca.workspace.yaml
name: "devflo"

overlays:
  network:
    enabled: true
    createIn: local-env
    disableAliases: false

projects:
- name: local-env
  base: true
  repository:
    self: true
- name: api
  repository:
    ssh: [email protected]:devflo-cloud/api.git
  requires:
    - local-env
- name: ui
  repository:
    ssh: [email protected]:devflo-cloud/ui.git
  requires:
    - local-env
- name: blog
  repository:
    ssh: [email protected]:devflo-cloud/blog.git
  requires:
    - local-env

requires gives orca a dependency graph, so orca up starts local-env (Traefik) before anything that sits behind it, and orca down stops things in the reverse order. Each repo also has a small orca.project.yaml next to its compose file. For the blog it’s almost nothing:

composeFiles:
  primary: docker-compose.yml

hosts:
  - blog.devflo.test

The local-env one additionally lists tlsCerts: ['*.devflo.test'].

Overlays

The part I like most is that orca doesn’t ask you to change your compose files. Instead it generates an overlay: an extra compose file, merged in with the normal -f a.yml -f b.yml mechanism, that adds the things that only matter in this workspace. Two overlays do the heavy lifting here:

  • Network. Every project is joined to one shared network (created in local-env, referenced as external by the others). Services also get a predictable alias, <service>.<project>.<workspace>.local, so a service in one project can reach a service in another by name, without anyone hardcoding IPs.
  • TLS injection. Orca generates certificates for the hosts in the workspace, and a single label on the Traefik service bind-mounts them in:
services:
  traefik:
    image: "traefik:v3.7.13"
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./etc/traefik/traefik.yaml:/etc/traefik/traefik.yaml"
      - "./etc/traefik/traefik-dynamic-config.yaml:/traefik-dynamic-config.yaml"
    labels:
      orca.pantoptescloud.tls/inject-certs: "/certs/"

If you ever want to see exactly what orca is doing, orca debug show-compose-config -p api prints the fully merged config, and orca debug show-compose-command -p api prints the docker compose -f … -p … prefix it uses. That second one is handy as $(orca debug show-compose-command -p api) ps for anything orca doesn’t wrap.

Traefik

Traefik discovers containers through the Docker socket and configures itself from their labels. The static config is small: HTTP redirects to HTTPS, a metrics entrypoint for Prometheus, and both the Docker and file providers. The file provider is only there to point at the certificates orca mounts into /certs:

tls:
  certificates:
    - certFile: /certs/_.devflo.test.cert
      keyFile: /certs/_.devflo.test.key

I’m running the latest release, v3.7.13. Worth a note for anyone copying the orca docs’ Traefik example, which is still pinned to v2.9.1: v2 and v3 have some real differences in router rule syntax (Headers became Header, HostHeader is gone, PathPrefix no longer takes a regex), so it’s worth checking the migration notes rather than assuming the example still matches the latest image. core.defaultRuleSyntax: v2 keeps the old behaviour if you need it. All my routers are plain Host() rules, so I didn’t.

Routing a service

Because the Docker provider is set to exposedByDefault: false, a service has to opt in. This is the entire block for the API:

services:
  api:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`api.devflo.test`)"
      - "traefik.http.routers.api.entrypoints=websecure"
      - "traefik.http.routers.api.tls=true"
      - "traefik.http.services.api.loadbalancer.server.port=8080"

The blog (blog.devflo.test → 3333), the app (app.devflo.test → 5173), and the marketing website (devflo.test → 3000) got the same treatment. Router names have to be unique across every project sharing the Traefik instance, so I named them after the service (api, app, website, blog).

Everything runs in the environment

The last piece is a rule rather than a tool. Every project’s tooling runs in its container through orca exec:

orca exec -p api -s api -- go test ./...
orca exec -p ui -s app -- pnpm --filter app run lint

Orca resolves the project from your working directory if you don’t pass -p, and exec uses docker compose exec when the service is running or a one-off run --rm when it isn’t. This matters more than it sounds: the UI’s node_modules is bind-mounted from the host, and running pnpm on macOS instead of in the Linux container can quietly install the wrong native bindings.

I also use AI coding agents on this project, and I wanted them held to the same rule. Rather than repeating instructions in every repo, the shared guidance lives in a single AGENTS.md in local-env, and each repo’s CLAUDE.md imports it with @../local-env/AGENTS.md. It says how to use orca, which commands are safe to run freely, and which ones to ask about first (down, restart, anything that touches /etc/hosts or generates certificates). Most importantly, if a task needs a tool that isn’t installed in any container, the agent has to stop and offer options: add it to the image, add a dedicated compose service, run it once in a throwaway container, or, only with my say-so, run it on the host.

Where this leaves things

orca up brings up Traefik, the API, the app, the website and the blog, all on real HTTPS hostnames, with each repo still holding a boring compose file. The next post covers the first feature that really uses all of it: logging in with GitHub, across the app and the API.