This is the GovOPlaN meta repository. It is the operator entry point for whole-product development, release orchestration, repository bootstrap, and system-level Docker composition.

It is not a runtime module. Runtime behavior belongs to govoplan-core and the installed modules/connectors discovered by core.

Common Commands

Create the whole-product development virtualenv in this meta repository:

python3 -m venv .venv
./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python --upgrade-pip

The meta venv is the default Python environment for launch, check, release, and Gitea tooling. GOVOPLAN_VENV_ROOT or PYTHON can override it for special cases.

Start the development stack through the meta repository:

./tools/launch/launch-dev.sh

Open the WebUI in a browser after launch only when explicitly requested:

GOVOPLAN_OPEN_BROWSER=1 ./tools/launch/launch-dev.sh

Limit backend reload triggers during focused module work without changing the enabled module graph:

GOVOPLAN_BACKEND_RELOAD_MODULES=calendar,campaign ./tools/launch/launch-dev.sh

Set GOVOPLAN_BACKEND_RELOAD_MODULES=none to watch only core/config sources. Leaving it unset keeps the broad default and watches all enabled modules.

Start the shared development PostgreSQL service:

./tools/launch/start-dev-postgres.sh

Check which GovOPlaN repositories are present and dirty:

./tools/repo/repo-status.sh

Clone missing repositories listed in repositories.json:

./tools/repo/bootstrap-repositories.py

Gitea Actions jobs bootstrap the registered repositories over HTTPS and reuse only the checkout job's short-lived authentication header. If registered modules are private, allow the meta repository read access under GovOPlaN -> Settings -> Actions -> General -> Cross-Repository Access; no long-lived personal token is stored by the workflow or bootstrap tool.

Update generated repository type notes in all READMEs:

./tools/repo/update-repository-type-notes.py

Regenerate the human-readable repository link index:

./tools/repo/generate-repository-index.py

Synchronize the Python environment after package metadata changes:

./.venv/bin/python tools/repo/sync-python-environment.py --requirements requirements-dev.txt --python ./.venv/bin/python

Run the static cross-repository module contract check:

./tools/checks/check-contracts.sh

Require backend, manifest, frontend, lockfile, and release-composition versions to agree before a release:

./.venv/bin/python tools/checks/check-version-alignment.py --release-composition

Generate the CycloneDX dependency inventory from a resolved release environment:

./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python

Synchronize module package workflows and inspect the registry release contract:

./.venv/bin/python tools/repo/sync-module-package-workflows.py --check
./.venv/bin/python tools/release/generate-release-package-set.py \
  --output /tmp/govoplan-release-packages.json

Package publication, exact artifact locking, and the optional govoplan developer meta-package are documented in Package Registry Releases.

For reproducible release artifacts, set SOURCE_DATE_EPOCH to the release commit timestamp (or pass an explicit timezone-qualified --timestamp):

SOURCE_DATE_EPOCH="$(git -C ../govoplan-core show -s --format=%ct HEAD)" \
  ./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python

Run the consolidated focused verification suite:

./tools/checks/check-focused.sh

Run the cross-repository dependency boundary gate:

./tools/checks/check_dependency_boundaries.py

Run installer rollback drills:

./tools/checks/module-installer-rollback-drill.py --format json

Release, catalog, Gitea, security-audit, and cross-repository maintenance commands should also be called from this repository through tools/.

Start the local release console:

./.venv/bin/python tools/release/release-console.py

Create and validate a private, declarative installation bundle:

./.venv/bin/python tools/deployment/govoplan-deploy.py init \
  --directory ~/.local/share/govoplan/installations/default
./.venv/bin/python tools/deployment/govoplan-deploy.py doctor \
  --directory ~/.local/share/govoplan/installations/default

The current executable slice and remaining production gates are documented in Installation and Deployment Architecture. The canonical distinction between local source development, split source integration, immutable single-host rehearsal, one-host production and multi-host Kubernetes production is in Deployment Profiles. Same-host replica balancing and the multi-host promotion boundary are documented in Scaling and Multi-Host Deployment. Create, update, pause, resume, verify and remove a local or multi-hypervisor K3s VM target with the guarded lifecycle documented in Kubernetes VM Test Lab. The recovery state machine, migration rollback boundary, and required restore drills are documented in Recovery and Rollback Guarantees.

Configuration

The repository root .env.example is the self-hosted operator template for a full GovOPlaN installation. Development profile examples live below dev/, for example dev/postgres/.env.example and dev/production-like/.env.example.

Do not commit populated .env files. Gitea tokens should stay in a local file such as ~/.config/gitea/gitea.env and be passed with --env-file.

Structure

Start with the documentation map. It separates stable strategy, architecture, operations, project reference, pinned evidence, and historical records and identifies the canonical source for each question.

The machine-readable repository list lives in repositories.json; the clickable directory is the Repository Index, and ownership boundaries are in Repository Structure.

GovOPlaN Docker

Whole-product Docker composition belongs in this meta repository.

Current module-specific Docker test beds remain in their owning repositories until they are migrated or wrapped here:

govoplan/dev/postgres
govoplan/dev/production-like
govoplan-campaign/dev/mail-testbed
govoplan-files/dev/connectors

The target shape is:

govoplan/dev/postgres: shared local development PostgreSQL service.
govoplan/dev/production-like: production-like validation composition.
module repositories keep only narrow connector or protocol test beds.

What doesn't belong here:

addideas-govoplan-website/docker-compose.yml: public website serving profile; this one stays with the website repository.