1666511475
- services/kb-postgres: pgvector/pgvector:pg16 na SOLARIA (:5433), named volume, init/001_envelope.sql (CREATE EXTENSION vector + zamrożona tabela envelope: id/source/ts/geo/raw_ref/entities), service.yaml, healthcheck, README z poprawnym mechanizmem deploy (deploy-node.sh składa dwa -f) - hosts/solaria/runtime/kb-postgres/docker-compose.override.yml: mem_limit 4g - inventory/topology.yaml + hosts/solaria/services.yaml: kb-postgres wpisany - packages/kb-mail: nowa konwencja shared lib (pip install /repo/packages/<lib>/) envelope.py — @dataclass Envelope, walidacja tz-aware ts db.py — insert_envelope / get_envelope (asyncpg, ON CONFLICT DO NOTHING) archive.py — save_eml append-only (asyncio.to_thread, FileExistsError na dup) tests: 15 unit pass + 5 integration (@pytest.mark.integration, wymaga KB_TEST_DSN) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# kb-postgres
|
|
|
|
Postgres 16 + pgvector — KB spine on SOLARIA. Stores the frozen envelope schema shared by all KB pillars (mails, documents, photos, transactions).
|
|
|
|
Port: **5433** on SOLARIA (Tailscale-accessible to other nodes).
|
|
|
|
## Standard deploy (from SATURN)
|
|
|
|
```bash
|
|
# On SATURN — pushes to master, then deploy.sh SSHes to SOLARIA and runs deploy-node.sh
|
|
git push origin master
|
|
scripts/deploy/deploy.sh solaria
|
|
```
|
|
|
|
`deploy-node.sh` on SOLARIA automatically picks up the per-host override:
|
|
```
|
|
docker compose \
|
|
-f services/kb-postgres/docker-compose.yml \
|
|
-f hosts/solaria/runtime/kb-postgres/docker-compose.override.yml \
|
|
up -d --remove-orphans
|
|
```
|
|
|
|
## First-time setup on SOLARIA (before first deploy)
|
|
|
|
The `.env` file must exist at `services/kb-postgres/.env` in the SOLARIA repo checkout
|
|
(alongside the compose file — that's where `env_file: .env` resolves to):
|
|
|
|
```bash
|
|
# On SOLARIA
|
|
cd ~/homelab-codex-ws
|
|
cp services/kb-postgres/env.example services/kb-postgres/.env
|
|
# Edit .env: set POSTGRES_PASSWORD to something strong
|
|
```
|
|
|
|
`.env` is gitignored (`*.env` rule in root `.gitignore`) — it will never be committed.
|
|
|
|
## Manual one-off (debugging / first boot)
|
|
|
|
```bash
|
|
# On SOLARIA, from repo root
|
|
docker compose \
|
|
-f services/kb-postgres/docker-compose.yml \
|
|
-f hosts/solaria/runtime/kb-postgres/docker-compose.override.yml \
|
|
up -d
|
|
```
|
|
|
|
## Verify after first boot
|
|
|
|
```bash
|
|
# Host-side healthcheck
|
|
./services/kb-postgres/healthcheck.sh
|
|
|
|
# Inside the container
|
|
docker exec kb-postgres psql -U kb -d kb -c '\d envelope'
|
|
docker exec kb-postgres psql -U kb -d kb \
|
|
-c "SELECT extname FROM pg_extension WHERE extname = 'vector';"
|
|
```
|
|
|
|
Expected `\d envelope` output:
|
|
|
|
```
|
|
Table "public.envelope"
|
|
Column | Type | Nullable | Default
|
|
----------+--------------------------+----------+-----------
|
|
id | text | not null |
|
|
source | text | not null |
|
|
ts | timestamp with time zone | not null |
|
|
geo | jsonb | |
|
|
raw_ref | text | not null |
|
|
entities | jsonb | not null | '[]'::jsonb
|
|
Indexes:
|
|
"envelope_pkey" PRIMARY KEY, btree (id)
|
|
"envelope_source_idx" btree (source)
|
|
"envelope_ts_idx" btree (ts)
|
|
```
|
|
|
|
## Schema contract
|
|
|
|
The `envelope` table is the frozen cross-source envelope (see `docs/kb/kb-00-overview.md` §Zasady przekrojowe). Adding columns is OK; removing or renaming existing ones is NOT.
|
|
|
|
Future migrations go in `init/` as `002_*.sql`, `003_*.sql`, …. Postgres runs `initdb` scripts only on a fresh volume — for existing instances apply migrations with `psql` directly.
|
|
|
|
## Connection string
|
|
|
|
```
|
|
postgresql://kb:<POSTGRES_PASSWORD>@solaria:5433/kb
|
|
```
|
|
|
|
Set `KB_TEST_DSN` to this value when running integration tests from `packages/kb-mail/`.
|