forkspace(active)
Isolated local dev/test environments for multi-repo compose stacks.
Isolated local dev/test environments for multi-repo compose stacks.
forkspace runs many copies of one Docker Compose stack on one machine. Git worktrees already give each branch or agent its own files, but every copy still reaches for the same port 3306 and the same MySQL data directory, so two test runs against “the” local database corrupt each other. forkspace gives each copy its own lane, and for each service in that lane it lets you choose how much to copy.
forkspace up dev
forkspace up test --fork agent-a
forkspace up test --fork agent-b
forkspace down test --fork agent-a
An environment in forkspace.yml lists the compose services it claims, and each
service declares an isolation level. A fork of that environment gets something
different from each level:
The usual test setup puts MySQL on namespace and everything else on shared:
one MySQL container holds a database per fork, while DynamoDB, the queue and
object storage stay single. A fork that needs its own MySQL after all asks for
it on the command line with --isolate mysql.
services:
mysql:
isolation: namespace
exports:
DATABASE_URL: "mysql://root:root@{host}:{port}/{ns}"
dynamodb:
isolation: shared
exports:
DYNAMO_ENDPOINT: "http://{host}:{port}"
forkspace names things; it does not drive databases. It mints the namespace
token from the fork name (lowercase, dashes become underscores, at most 32
characters), so agent-a becomes agent_a, fills it into the export templates,
and writes the result to an env file the tests source. Creating and dropping
the database is the job of your repo’s own hook scripts: a fork runs
forkCreate then seed on the way up and forkDestroy on the way down.
Each fork takes a slot, the lowest one whose ports are free, and every port it
owns is the service’s base port plus the slot times slotSize:
A fork must never land on another service’s baseline port. forkspace check
tests the config for that before anything starts: two services whose base ports
sit a whole number of slots apart, fewer than 32, are an error, unless they are
the same compose service shared between environments. Each instance is also its
own compose project, fs-<workspace>-<env>-<fork>, so containers and volumes
never share names.
An environment marked persistent, like dev, keeps its volumes through
down. Any other environment drops them, so a test run starts clean, seeded,
and with no state left from the previous one. A baseline runs bootstrap then
seed when it comes up.
A browser playground simulates forkspace without Docker: a terminal, guided
scenarios, a command panel and a live forkspace.yml editor.
Try it. The full command reference, hooks
and env contract are in the
GitHub README.