bogdan Document SQLite runtime database

d68d38e 4 days ago History

# Madagascar Local Authority

Local authority for Madagascar hosts, DNS manifests, work orders, and host certificates.

The development checkout lives locally at:

```text
/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
```

The canonical GitPrep repository is:

```text
git@192.168.2.102:repositories/bogdan/LocalAuthority.git
```

The runtime instance lives on jumper and remains the local source for operational registry data:

- `var/host-manager.sqlite` - runtime source of truth for host registry and Work Orders
- `config/hosts.yaml` - seed/snapshot export for host registry compatibility
- `config/local-hosts.tsv` - DNS manifest exported for local resolvers
- `config/work-orders.yaml` - seed/snapshot export for confirmable operational changes
- `scripts/host_manager.pl` - Perl-only web app
- `scripts/sync_local_hosts.sh` - local DNS sync to jumper and as01
- `scripts/ca_manager.sh` - local OpenSSL CA helper for host certificates

The public `xdev.ro` zone is maintained in the separate DNS public-zone repository.

Runtime path:

```text
/usr/local/xdev-host-manager
```

Secrets live outside git in `/etc/xdev/host-manager.env`.

The product name is **Madagascar Local Authority**. The technical service, Unix user, repository path, and environment files still use `host-manager`.

The web UI is OTP-protected for all registry data, downloads, exports, and writes. Automation should consume generated exports with dedicated read-only access, not unauthenticated HTTP.

For agent/operator context, see:

- [`agents.md`](agents.md)
- [`.doc/database.md`](.doc/database.md)
- [`.doc/development-log.md`](.doc/development-log.md)
- [`.doc/host-manager.md`](.doc/host-manager.md)
- [`.doc/local-hosts.md`](.doc/local-hosts.md)

## Local development and live testing

Work on application code locally. Do not leave changes parked in a dirty working
tree; commit small, coherent changes so they cannot be lost during deploy,
reset, or context switches.

```bash
cd /Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
git status --short
git add ...
git commit -m "Describe the change"
```

For live testing, push the committed code to the runtime checkout on jumper:

```bash
git push jumper-runtime HEAD:main
```

The jumper receive hook validates the Perl scripts, restarts `host-manager`,
writes `BUILD`, and checks `/healthz`.

For archival/canonical history, push the same commits to GitPrep:

```bash
git push origin main
```

`scripts/deploy_to_jumper.sh` remains available as an explicit rsync deploy
tool, but the normal development loop is commit plus push: `jumper-runtime` for
live testing, `origin`/GitPrep for archive and sharing.

`config/` is not deployed by default. The live source of truth is `var/host-manager.sqlite`; `hosts.yaml`, `local-hosts.tsv`, and `work-orders.yaml` are seed/snapshot/export files that should not replace runtime data during normal code pushes. Deploy config only when intentionally replacing seed/export files:

```bash
scripts/deploy_to_jumper.sh --include-config
```

The default internal domain is `madagascar.xdev.ro`. Short aliases are derived automatically from FQDNs, so `autonas01.madagascar.xdev.ro` also publishes `autonas01` without declaring it separately.

Name removals with operational impact go through a Work Order. A WO records intent first; the operational checklist must be completed before confirmation can update the SQLite registry, mark the WO as confirmed, and regenerate `local-hosts.tsv`. Resolver sync remains an explicit operator step.

The local host CA stores private material outside git under `var/ca`. Initialize it on jumper with:

```bash
sudo scripts/ca_manager.sh init
```