a1a57b04bb
Serwisy o jednorodnej tresci (bez wydzielonej sekcji deploy/runbook): kb-postgres, stability-agent, llm-gateway, vikunja, zigbee2mqtt, npm, forgejo, ollama, ir-ac-ha-integration, chelsty-stability-agent. Deprecated: mosquitto (NOT DEPLOYED/LEGACY), home-assistant-ken-legacy (archiwum importu), joplin (stub z 2026-04-15, brak katalogu services/joplin/). git mv + frontmatter, tresc nietknieta. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
113 lines
3.7 KiB
Markdown
113 lines
3.7 KiB
Markdown
---
|
|
okf: "0.1"
|
|
type: service
|
|
visibility: private
|
|
status: active
|
|
updated: 2026-06-22
|
|
links: []
|
|
---
|
|
|
|
# kb-postgres
|
|
|
|
Postgres 16 + pgvector — KB spine on **PIHA** (Raspberry Pi 5, always-on). Stores the frozen envelope schema shared by all KB pillars (mails, documents, photos, transactions).
|
|
|
|
Runs here because the KB store must answer queries 24/7; SOLARIA (GPU/compute) is powered down intermittently. Embeddings/models still run on SOLARIA's GPU — only the Postgres+pgvector store lives on PIHA. The `pgvector/pgvector:pg16` image is multi-arch and runs natively on arm64 (the Pi 5).
|
|
|
|
Port: **5433** on PIHA (Tailscale-accessible to other nodes).
|
|
|
|
## Standard deploy (from SATURN)
|
|
|
|
```bash
|
|
# On SATURN — pushes to master, then deploy.sh SSHes to PIHA and runs deploy-node.sh
|
|
git push origin master
|
|
scripts/deploy/deploy.sh piha
|
|
```
|
|
|
|
`deploy-node.sh` on PIHA automatically picks up the per-host override:
|
|
```
|
|
docker compose \
|
|
-f services/kb-postgres/docker-compose.yml \
|
|
-f hosts/piha/runtime/kb-postgres/docker-compose.override.yml \
|
|
up -d --remove-orphans
|
|
```
|
|
|
|
The PIHA override caps memory (`mem_limit: 1g`) and tunes Postgres for a tight,
|
|
HA-shared RAM budget. Data lives in the `kb_postgres_data` named volume, which
|
|
**must** land on the NVMe (Docker data-root on `/home`), never the SD card —
|
|
verify before first deploy (see the override file's DATA PLACEMENT note):
|
|
|
|
```bash
|
|
# On PIHA
|
|
docker info -f '{{.DockerRootDir}}' # expect an NVMe path
|
|
df -h "$(docker info -f '{{.DockerRootDir}}')" # confirm it's the NVMe
|
|
```
|
|
|
|
## First-time setup on PIHA (before first deploy)
|
|
|
|
The `.env` file must exist at `services/kb-postgres/.env` in the PIHA repo checkout
|
|
(alongside the compose file — that's where `env_file: .env` resolves to):
|
|
|
|
```bash
|
|
# On PIHA
|
|
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 PIHA, from repo root
|
|
docker compose \
|
|
-f services/kb-postgres/docker-compose.yml \
|
|
-f hosts/piha/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>@piha:5433/kb
|
|
```
|
|
|
|
Set `KB_TEST_DSN` to this value when running integration tests from `packages/kb-mail/`
|
|
(host = `piha` over Tailscale).
|