Foundry Instance Manager

The problem

Running several Foundry VTT campaigns means juggling different versions, modules and worlds. I wanted each campaign in its own container, with its own data, but sharing assets so I was not duplicating large libraries.

Key design decisions

Containers from one image, data kept outside. Each instance gets its own data directory and all instances can see a shared directory, so an instance can be removed or recreated without losing its world. Containers are driven through the Docker SDK rather than shelled-out commands.

Separate managers by concern. The package splits the work into modules for instances, worlds, modules, game systems, assets and instance records, with a Click CLI on top and Rich for output. That kept each piece testable, with a test module per area.

Automation first. The repository has CI for lint, type checking (mypy), tests and security scanning (Bandit, Safety), and automated version bumping and changelog generation on pushes to main. In hindsight I put a lot of effort here before the tool itself was stable, and the repo’s own technical-debt notes record CI authentication and version-bumping problems I had to fix along the way.

Stack

Python 3.9+, Click, the Docker SDK, Poetry, pytest, Black, isort, flake8 and mypy.

Outcome and what I would change

The public repo has about 137 commits, dated 2025-05-29 to 2025-06-28. The README still says the project is in progress and not ready for use, and I have left that warning in. Its name lives on in the control plane of my fim2 platform. There is also a tutorial post on the blog about building it. What I would change: stabilise the core create, start, stop and remove commands and their dependency injection (the Docker client is instantiated directly, which the debt notes flag) before building release automation.