SpiriConfig

Plugin-based configuration and container management, built around one rule:

Anything SpiriConfig can do, you must be able to do without it.

Press Up on a stack in the web UI and SpiriConfig runs this, showing you the line as it goes, with a button to copy it:

cd /srv/compose/whoami && docker compose -p whoami -f compose.yaml up -d

No database, no registry, no bespoke on-disk format. If SpiriConfig vanished tomorrow, everything it manages would keep working -- and you would already know the commands to manage it.

Installation

Every service SpiriConfig manages runs in a container; SpiriConfig itself cannot, because the process that starts those containers on boot has to live on the host. So it installs itself as a systemd service. You need uv on the machine, then:

uvx spiriconfig install

That pulls the latest release from PyPI, writes a systemd unit and an environment file, and enables and starts the service -- the web UI comes up on http://localhost:8080 and returns on every boot. Add --show to print every command it will run before it runs anything.

Run it as root for a system-wide service, or as a normal user for a single-operator systemctl --user one; that choice is the security model, not a preference. Update in place with spiriconfig update. See Installing SpiriConfig for the full walkthrough.

To track the latest development instead of a release, install from git -- the positional argument is anything uv accepts:

spiriconfig install git+https://github.com/spiri-robotics/SpiriConfig.git

A git-branch install pins to a commit, so spiriconfig update --reinstall refetches the branch when it moves.

Usage

Point it at your compose directory and start the web UI:

export SPIRICONFIG_DOCKER_COMPOSE_DIR=/srv/compose
spiriconfig serve            # web UI on http://localhost:8080

Adding a service is making a directory. No CLI required -- that is the point:

sudo mkdir -p /srv/compose/whoami
sudo $EDITOR /srv/compose/whoami/compose.yaml

A non-root install defaults its compose directory to ~/spiri-apps, so dropping your own in-development project there -- a directory with a compose.yaml -- is all it takes to get started; SpiriConfig picks it up as a stack, no install step. Add a compose.dev.yaml alongside it to build from source and get the dev-mode "Up (dev)" path.

From the shell:

spiriconfig docker list
whoami   running
grafana  stopped

spiriconfig docker up whoami
spiriconfig docker logs whoami -f

Not sure what a command will do? Ask, without running it:

spiriconfig docker up whoami --show
cd /srv/compose/whoami && docker compose -p whoami -f compose.yaml up -d

Because the compose project name is the directory name, these are the same containers you get from running compose yourself -- SpiriConfig and a plain shell can manage the same stack on the same afternoon without confusing each other.

Configuration

Environment variables only. See the docs for the full list; the one you need is:

The defaults are relative on purpose: running out of a checkout should not start managing the containers on your actual box. See configuration.

Plugins

The docker plugin is the only one that ships, and it is not special: it is discovered through the spiriconfig.plugins entry point group exactly as yours would be.

[project.entry-points."spiriconfig.plugins"]
tailscale = "spiriconfig_tailscale:TailscalePlugin"

Install the package and it appears in the CLI and the web UI. See docs/plugins.md for the interface and the rules, and docs/design.md for why the rules exist.

Development

Work from a checkout with uv:

uv sync

You can drive the whole flow without touching your real machine. test_data/ is gitignored and disposable, and the default settings point at it, so trying SpiriConfig out cannot start managing the containers on your box:

./scripts/test-data.sh                        # a compose dir + an example app store
uv run spiriconfig appstore check
uv run spiriconfig appstore install whoami
uv run spiriconfig docker up whoami
uv run spiriconfig serve &
curl localhost:8337/plugin/whoami/
Hostname: 2d5bcd6f2629
GET / HTTP/1.1

whoami publishes no port of its own -- the reverse proxy above is the only way in, same as any other plugin (see spiriconfig.plugin.* labels in examples/store/whoami/compose.yaml).

Run the tests and build the docs:

uv run pytest                                   # 92 tests
uv run sphinx-build -b html docs docs/_build    # docs

Tests that need a docker daemon are skipped when there is not one, so the suite passes on a laptop with no docker and still means something on a machine that has it. Most of them never need one anyway: the plugin builds commands and the tests assert on the command line, which is the actual contract.