# GovOPlaN **Repository type:** system (meta). [![Module Matrix](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/module-matrix.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=module-matrix.yml&actor=0&status=0) [![Release Integration](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/release-integration.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=release-integration.yml&actor=0&status=0) [![Deployment Installer](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/deployment-installer.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=deployment-installer.yml&actor=0&status=0) [![Dependency Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/dependency-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=dependency-audit.yml&actor=0&status=0) [![Security Audit](https://git.add-ideas.de/GovOPlaN/govoplan/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=security-audit.yml&actor=0&status=0) 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: ```sh 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: ```sh ./tools/launch/launch-dev.sh ``` Open the WebUI in a browser after launch only when explicitly requested: ```sh GOVOPLAN_OPEN_BROWSER=1 ./tools/launch/launch-dev.sh ``` Limit backend reload triggers during focused module work without changing the enabled module graph: ```sh 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: ```sh ./tools/launch/start-dev-postgres.sh ``` Check which GovOPlaN repositories are present and dirty: ```sh ./tools/repo/repo-status.sh ``` Clone missing repositories listed in `repositories.json`: ```sh ./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: ```sh ./tools/repo/update-repository-type-notes.py ``` Regenerate the human-readable repository link index: ```sh ./tools/repo/generate-repository-index.py ``` Synchronize the Python environment after package metadata changes: ```sh ./.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: ```sh ./tools/checks/check-contracts.sh ``` Require backend, manifest, frontend, lockfile, and release-composition versions to agree before a release: ```sh ./.venv/bin/python tools/checks/check-version-alignment.py --release-composition ``` Generate the CycloneDX dependency inventory from a resolved release environment: ```sh ./.venv/bin/python tools/release/generate-release-sbom.py --python ./.venv/bin/python ``` Synchronize module package workflows and inspect the registry release contract: ```sh ./.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](docs/operations/PACKAGE_REGISTRY_RELEASES.md). For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release commit timestamp (or pass an explicit timezone-qualified `--timestamp`): ```sh 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: ```sh ./tools/checks/check-focused.sh ``` Run the cross-repository dependency boundary gate: ```sh ./tools/checks/check_dependency_boundaries.py ``` Run installer rollback drills: ```sh ./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: ```sh ./.venv/bin/python tools/release/release-console.py ``` Create and validate a private, declarative installation bundle: ```sh ./.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](docs/operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). 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](docs/operations/DEPLOYMENT_PROFILES.md). Same-host replica balancing and the multi-host promotion boundary are documented in [Scaling and Multi-Host Deployment](docs/operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). 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](docs/operations/KUBERNETES_TEST_LAB.md). The recovery state machine, migration rollback boundary, and required restore drills are documented in [Recovery and Rollback Guarantees](docs/operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md). ## 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](docs/README.md). 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](docs/project/REPOSITORY_INDEX.md), and ownership boundaries are in [Repository Structure](docs/project/REPOSITORY_STRUCTURE.md). # 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.