zemion
2ffdb23f69
Verified with the coordinated workspace changes by devkit full run 2026-09-08T225814-186389-0000-3e3ed7cd (all seven phases passed). This shared UI pass does not mark the individual module reviews complete.
240 lines
8.6 KiB
Markdown
240 lines
8.6 KiB
Markdown
# GovOPlaN
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** system (meta).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
[](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=module-matrix.yml&actor=0&status=0)
|
|
[](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=release-integration.yml&actor=0&status=0)
|
|
[](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=deployment-installer.yml&actor=0&status=0)
|
|
[](https://git.add-ideas.de/GovOPlaN/govoplan/actions?workflow=dependency-audit.yml&actor=0&status=0)
|
|
[](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
|
|
|
|
For repeated development and review workflows, start with the unified command
|
|
suite. [Developer command guide](docs/operations/DEVKIT.md) documents profiles,
|
|
evidence, safe Git/release operations and reuse in other projects.
|
|
|
|
```sh
|
|
./devkit commands
|
|
./devkit context --changed
|
|
./devkit check --profile quick --changed --dry-run
|
|
./devkit review campaign
|
|
```
|
|
|
|
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.
|