versionist

versionist discovers stable evcc releases and pull-request images, then replaces one configured Docker container while preserving its runtime configuration. Replacements are journaled and rolled back when creation, startup, or health checks fail.

Configuration

Variable	Default	Purpose
VERSIONIST_BEARER_TOKEN	required	Bearer token for every /api/ endpoint
VERSIONIST_LISTEN	:8080	HTTP listen address
VERSIONIST_TARGET_CONTAINER	evcc	Fixed container managed by versionist
VERSIONIST_GITHUB_TOKEN	empty	Optional token for authenticated GitHub release and PR discovery
VERSIONIST_JOURNAL_PATH	/var/lib/versionist/state.json	Atomic transaction journal
VERSIONIST_GITHUB_BASE_URL	https://api.github.com	GitHub API base URL, primarily for tests
VERSIONIST_HUB_BASE_URL	https://hub.docker.com	Docker Hub API base URL, primarily for tests

Running

Mount the Docker socket and persistent journal directory. Access to the Docker socket is equivalent to root authority over the Docker host. Protect the bearer token and do not expose this service to an untrusted network.

docker build -t versionist:latest .

The runtime image uses a non-root user. Grant its process the Docker socket's numeric group with --group-add; the group ID varies by host.

docker run --rm \
  --name versionist \
  --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v versionist-state:/var/lib/versionist \
  -e VERSIONIST_BEARER_TOKEN='replace-me' \
  versionist:latest

Compose-generated containers may contain project labels, generated names, and dependency wiring that Compose expects to own. A versionist replacement preserves the inspected Docker configuration, but it does not rewrite Compose state. A later docker compose up may recreate or replace the container according to the Compose model.

Containers configured with AutoRemove are rejected because Docker could remove the rollback source. The original restart policy is disabled before stopping. The old container is retained under a transaction name until the candidate is healthy; failures remove only the recorded candidate identity and restore the original. The first successful switch records the initial image digest, and revert applies that digest using the current runtime configuration.

Pull-request choices are an explicit operator trust boundary. Official maintainer-triggered pr-N images execute code from that pull request with the target evcc container's mounts, environment, devices, network access, and other Docker privileges. Digest immutability prevents the selected image from changing, but it does not cryptographically bind that image to the current head SHA displayed by versionist. Operators must trust the evcc build and publication process before activating a PR image.

API

Health and startup readiness are public:

curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz

All operational endpoints require the bearer token:

curl -H 'Authorization: Bearer replace-me' http://127.0.0.1:8080/api/choices
curl -H 'Authorization: Bearer replace-me' http://127.0.0.1:8080/api/state

curl -X POST \
  -H 'Authorization: Bearer replace-me' \
  -H 'Content-Type: application/json' \
  -d '{"choiceId":"release:0.202"}' \
  http://127.0.0.1:8080/api/operations/activate

curl -X POST \
  -H 'Authorization: Bearer replace-me' \
  http://127.0.0.1:8080/api/operations/revert

curl -H 'Authorization: Bearer replace-me' \
  http://127.0.0.1:8080/api/operations/OPERATION_ID

Activation accepts only a catalog choiceId; clients cannot submit an image or container name. Accepted operations return 202, a concurrent operation returns 409, and unknown choices or operation IDs return 404.