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

The repository categories are documented in docs/REPOSITORY_STRUCTURE.md. The machine-readable list lives in repositories.json; the clickable human-readable index is docs/REPOSITORY_INDEX.md.

Meta ownership and module install/contract boundaries are documented in docs/META_REPO_SCAN.md and docs/MODULE_CONTRACTS_AND_INSTALLS.md. Frontend layout principles for module pages are documented in docs/FRONTEND_LAYOUT_PRINCIPLES.md. The provider-neutral datasource boundary and reusable Dataflow/Workflow graph contract are documented in docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md. The cross-product destination, stakeholder visions, configuration archetypes, connected outcome stories, and capability horizons are documented in the Connected Governance Platform Roadmap. The reconciled institutional semantics, source-authority modes, module layers, candidate Mandates/Services/Parties/Decisions boundaries, and migration sequence are documented in the Institutional Governance Target Architecture. The selected Campaign-to-Postbox-to-data-to-collaboration implementation path, including stage gates and shared documentation expectations, is in the Reference Journey Program. The administrator journey from a Core-baseline bootstrap through online module installation, scale-out, and reversible environment promotion is defined in System Administrator Lifecycle User Story. The corresponding host deployment compiler, managed/external component choices, reconfiguration semantics, and safe Web update boundary are defined in Installation and Deployment Architecture. The concrete replica, worker-node, load-balancer, and shared-state topology is defined in Scaling and Multi-Host Deployment. Durable deployment journals, Core recovery evidence, and the distinction between pre-migration configuration restore and post-migration forward recovery are defined in Recovery and Rollback Guarantees. The first Campaign-centric capability and infrastructure fit assessment is in docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md. Its rerun tooling can collect and verify a bounded installed composition; target, provider and production claims remain separate, expiring attestations signed by independently scoped proof authorities. The operational issuance, target-run, recovery-measurement, key custody, and promotion-gate procedure is in Target Maturity Evidence Runbook.

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.