feat: multi-instance overlay pattern — kennung + port collision check#7
Merged
Merged
Conversation
added 2 commits
June 3, 2026 21:58
wp-test-env v2.0.0 already supported per-instance state via
COMPOSE_PROJECT_NAME + COMPOSE_PROJECT_DIR, but it didn't:
1. Codify the "overlay declares its kennung" convention.
2. Fail fast when overlays pick colliding ports.
3. Document how two overlays coexist on the same machine.
This commit adds:
- `scripts/check-ports.sh` — pre-flight port collision check. Reads
ports from .env (or accepts args). Probes Docker containers AND host
processes (via lsof/ss/netstat). Reports each occupied port with what
holds it. Exit 1 + actionable resolution hints on collision.
- `scripts/setup.sh` — calls check-ports.sh before `docker compose up`.
Skipped on --fresh (own containers will be torn down anyway).
- `docs/overlay-pattern.md` — codifies the convention:
* COMPOSE_PROJECT_NAME = "kennung" (kebab-case, `-wptest` suffix)
* Port band table for sequential overlays
* Required overlay structure
* Coexistence example (elementeer + capacium running in parallel)
* Decision log (why these choices)
- `.env.example` — documents the kennung convention in-line; adds
capacium-wptest as a second concrete example next to elementeer.
This is the template-level foundation for letting plugin/theme overlays
ship their own `.env.overlay` with a unique kennung + port band, run
`check-ports.sh`, then `setup.sh` — coexisting cleanly with any other
overlay's stack on the same dev machine.
Verified locally:
- check-ports.sh detects existing wptesting-wordpress container holding 8082
- check-ports.sh passes when given unused ports (8999/9000/9001)
- setup.sh's check_ports() invocation correctly aborts when port taken
… in .env.example Follow-up to the previous commit: - setup.sh now calls check_ports() before docker compose up (skipped on --fresh since own containers will be torn down). - .env.example documents the kennung convention in-line: kebab-case COMPOSE_PROJECT_NAME with `-wptest` suffix, distinct per overlay, e.g. `elementeer-wptest` vs `capacium-wptest`. These two changes complete the template-level support for the overlay pattern. Overlay setup scripts can now rely on: - Their kennung being honored (COMPOSE_PROJECT_NAME applied via .env) - Port collisions failing fast with a clear error before docker compose fights itself
added 3 commits
June 3, 2026 22:05
…HEMES_DIR/UPLOADS_DIR
The previous multi-instance support (COMPOSE_PROJECT_NAME + COMPOSE_PROJECT_DIR)
isolated container names, networks, and Docker-managed volumes — but left
the HOST BIND MOUNTS pointing at ./plugins, ./themes, ./uploads
unconditionally. Two overlays sharing the same wp-test-env checkout
would mount the SAME host plugins/ dir into both wordpress containers
→ overlay A's plugin install pollutes overlay B's filesystem.
This commit fixes that:
- docker-compose.yml: bind-mount paths now use ${PLUGINS_DIR:-./plugins},
${THEMES_DIR:-./themes}, ${UPLOADS_DIR:-./uploads}. Default behavior
for the first/primary instance is unchanged (uses repo-root dirs).
- .env.example: documents the new vars with a per-overlay example
(envs/<name>/plugins) + explains why they exist (CRITICAL for isolation).
- scripts/setup.sh: creates the per-instance dirs on first run if they
don't exist, and seeds PLUGINS_DIR with the canonical free plugin
bundle from ./plugins so the overlay starts with a working baseline
(Query Monitor, Debug Bar, User Switching, WP Importer).
Together with check-ports.sh (port collision pre-flight), wp-test-env
now provides genuine multi-instance isolation:
- Distinct container/network/volume names (via COMPOSE_PROJECT_NAME)
- Distinct state dirs (via COMPOSE_PROJECT_DIR)
- Distinct plugins/themes/uploads bind mounts (via *_DIR vars)
- Distinct ports (via PORT vars + check-ports.sh)
Verified by running capacium-bridge-tests overlay alongside elementeer
overlay on the same machine — no cross-pollution, both stacks usable.
…erlays only)
Two related hygiene fixes:
1. AGENTS.md (NEW, top-level) — clear guidance for AI dev agents and
humans landing here: this is a template, you consume it from your
project's overlay, you don't fork it to add project-specific stuff.
Includes:
- Visual diagram of template → overlay relationship
- Minimum `.env.overlay` example with kennung + port band + paths
- Minimum `setup-overlay.sh` shape
- Common pitfalls table (e.g. `docker exec wptesting-wordpress`
blindly hitting whatever overlay holds the default container name)
- "Can I change this in the template?" decision table
- Reference to capacium-bridge-tests + elementeer-ops/wp-testing-env
as real-world overlay examples
2. .gitignore + remove tracked plugin zips: the 4 free-tool zips
(Query Monitor, Debug Bar, User Switching, WP Importer) that lived
in plugins/ were tracked in git. The template must stay GENERIC —
it shouldn't bake in a particular plugin selection. Overlays bring
their own via config/plugins.yaml (which uses source: wordpress.org
to fetch them at install time anyway).
- .gitignore now excludes plugins/* but allows plugins/README.md
as the dir marker
- 4 zips removed via `git rm --cached`; remain on disk for any
existing local checkouts that already had them
3. setup.sh: dropped the "seed plugins/ from ./plugins" logic that
relied on the template having a plugins/ bundle. Now just creates
the per-instance bind-mount dirs and lets the overlay's
`setup-overlay.sh` populate them (via config/plugins.yaml install
step or direct cp from the project source dir).
Verified with capacium-bridge-tests overlay: setup-overlay.sh creates
PLUGINS_DIR, runs base setup.sh, then overlay drops the bridge plugin
into the isolated dir — no reliance on template-shipped plugins.
dev-bot-capacium
approved these changes
Jun 4, 2026
dev-bot-capacium
left a comment
dev-bot-capacium
left a comment
There was a problem hiding this comment.
Reviewed locally with capacium-bridge-tests overlay running alongside elementeer's wptesting on the same machine — full isolation verified (distinct kennung, distinct ports, distinct plugins dir, no cross-pollution). AGENTS.md gives dev agents a clear hands-off-template / work-in-overlay rule. Approved via dev-bot.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
wp-test-env v2.0.0 already supports per-instance state via
COMPOSE_PROJECT_NAME+COMPOSE_PROJECT_DIR, but it didn't:Today we hit this in practice: deploying
capacium-bridgefor testing accidentally polluted the runningelementeertest env because both use the same container names (defaultwptesting-*).What changed
scripts/check-ports.sh(NEW) — pre-flight port collision check. Reads.env(or accepts arg ports). Probes Docker containers AND host processes (lsof / ss / netstat). Reports each occupied port + what holds it. Exit 1 + actionable resolution hints on collision.scripts/setup.sh— callscheck_ports()beforedocker compose up. Skipped on--fresh(own containers will be torn down anyway)..env.example— documents the kennung convention in-line with concrete examples (elementeer-wptest,capacium-wptest).docs/overlay-pattern.md(NEW) — codifies the convention: naming, port allocation table, required overlay structure, coexistence example, decision log.Test plan