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/`.
|