duckeighty

duckeighty

Duckeighty is a local HTTPS ingress layer for running multiple Docker Compose applications, and multiple worktrees of the same application, on a single machine without forcing the applications themselves to become multi-environment aware.

Duckeighty gives each exposed service a stable local URL in this form:

https://{project_name}-{service_name}.duckeighty.test

Examples:

• https://blog-main-web.duckeighty.test
• https://blog-feature-foo-web.duckeighty.test
• https://blog-feature-foo-admin.duckeighty.test

The intended outcome is simple:

• each application service only needs to listen on 8080 inside its container
• the host does not need a growing list of published ports
• multiple worktrees can run at the same time
• existing Compose applications can opt in with a small local override file
• local HTTPS works without public tunnels

This document is written so that both humans and coding agents can implement and validate the system.

---

What duckeighty does

Duckeighty provides:

• a shared local ingress stack built with Traefik
• local wildcard DNS for *.duckeighty.test
• local TLS using a local CA
• a reusable Docker network shared by many Compose projects
• a small per-application docker-compose.local.yaml override pattern

Duckeighty does not require applications to know about branches, worktrees, or multi-tenant routing. Applications only need to expose an HTTP service inside the container.

---

How it works

At a high level, duckeighty works like this:

Browser
  -> https://<project>-<service>.duckeighty.test
  -> local DNS resolves *.duckeighty.test to 127.0.0.1
  -> Traefik on the host-facing ingress stack
  -> shared Docker network (shared_ingress)
  -> target service on port 8080 inside a Compose project

The architecture has three parts:

1. Ingress stack

   • runs Traefik
   • runs local DNS
   • owns the shared Docker network used for ingress
   • terminates TLS using a locally trusted certificate

2. Application stack

   • remains a normal Docker Compose app
   • joins the shared ingress network through a local override file
   • adds Traefik labels describing the hostname and backend port

3. Host setup

   • trusts a local CA using mkcert
   • routes duckeighty.test DNS queries to the local DNS service

---

Naming model

Duckeighty routes services by project name and service name.

Public hostname format:

{project_name}-{service_name}.duckeighty.test

Project name

The Compose project name is the environment boundary. In practice this comes from COMPOSE_PROJECT_NAME or docker compose -p ....

Each worktree should use a distinct project name.

Examples:

• main
• feature-foo
• feature-login-redesign

Service name

The service name is the key under services: in the Compose file.

Examples:

• web
• admin
• api

Project name normalization

Project names should be normalized before being used in hostnames.

Normalization rules:

• lowercase everything
• replace / with -
• replace . with -
• optionally replace other non-alphanumeric characters with -
• collisions are allowed

Examples:

• feature/foo -> feature-foo
• feature.foo -> feature-foo
• Feature/Foo.Bar -> feature-foo-bar

A practical implementation should pass a normalized value separately, for example as DUCKEIGHTY_PROJECT_NAME.

---

Repository layout

.
├── README.md
├── duckeighty.sh                         # single CLI entry point (setup-ca / setup-resolver / up / check)
├── infra/
│   ├── compose.yaml                      # traefik + dnsmasq, compose project name `duckeighty`
│   ├── traefik/
│   │   ├── traefik.yaml                  # static config, HTTP→HTTPS redirect
│   │   └── dynamic/tls.yaml              # wildcard cert via file provider
│   ├── dns/dnsmasq.conf                  # address=/duckeighty.test/127.0.0.1
│   └── certs/                            # mkcert output, gitignored
├── templates/
│   └── docker-compose.local.yaml         # per-app override template
├── skills/                               # agent skills (open SKILL.md spec)
│   ├── duckeighty-init/SKILL.md
│   ├── duckeighty-doctor/SKILL.md
│   └── duckeighty-integrate/
│       ├── SKILL.md
│       └── references/
├── examples/
│   └── simple-app/                       # nginx:alpine + envsubst, no Dockerfile
│       ├── compose.yaml
│       ├── docker-compose.local.yaml
│       └── default.conf.template
└── .claude-plugin/
    ├── plugin.json                       # Claude Code plugin manifest
    └── marketplace.json                  # self-listing single-plugin marketplace

The implementation includes:

• an ingress stack (infra/)
• an application override template (templates/)
• a single CLI entry point (duckeighty.sh)
• one runnable example (examples/simple-app/)
• three agent skills (skills/duckeighty-{init,doctor,integrate}/)

---

Ingress stack