Sync Repo-README from project files
+241
@@ -0,0 +1,241 @@
|
||||
<!-- codex-wiki-sync:28496fdfb2db07160032de9f -->
|
||||
|
||||
> Mirrored from `/mnt/DATA/git/govoplan/README.md`.
|
||||
> Origin: `repository`.
|
||||
> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
|
||||
|
||||
---
|
||||
# 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md).
|
||||
Same-host replica balancing and the multi-host promotion boundary are documented
|
||||
in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md).
|
||||
The recovery state machine, migration rollback boundary, and required restore
|
||||
drills are documented in
|
||||
[Recovery and Rollback Guarantees](docs/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
|
||||
|
||||
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](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md).
|
||||
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](docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
|
||||
The selected Campaign-to-Postbox-to-data-to-collaboration implementation path,
|
||||
including stage gates and shared documentation expectations, is in the
|
||||
[Reference Journey Program](docs/REFERENCE_JOURNEY_PROGRAM.md).
|
||||
The administrator journey from Core-only bootstrap through online module
|
||||
installation, scale-out, and reversible environment promotion is defined in
|
||||
[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md).
|
||||
The corresponding host deployment compiler, managed/external component choices,
|
||||
reconfiguration semantics, and safe Web update boundary are defined in
|
||||
[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md).
|
||||
The concrete replica, worker-node, load-balancer, and shared-state topology is
|
||||
defined in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md).
|
||||
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](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md).
|
||||
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.
|
||||
|
||||
# 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.
|
||||
Reference in New Issue
Block a user