Void-Homelab/docs/plan-1-complete.md

Plan 1 Complete — Foundation

Done: 2026-05-31

What landed

• Two LXCs provisioned: void2-db (CT 310 @ 192.168.1.15 — Postgres 16.14 + pgvector 0.8.2 + pgcrypto) and void2-app (CT 311 — Node 22 + Express)
• PVE replication jobs 310-0 and 311-0 to Z3 every 15 min for pct migrate-based HA
• Schema migrations 001-006:
  • 001 core (spaces, projects, tasks) with composite-FK tenancy
  • 002 knowledge (pages, page_revisions, refs) with FTS + vector indexes
  • 003 resources, resource_dependencies, resource_credentials, source_docs (composite FKs on both endpoints, source_docs anchored by NOT NULL FK)
  • 004 agents, agent_tokens (bcrypt), conversations, messages (FTS GIN)
  • 005 tags, entity_tags, entity_links, attachments (polymorphic — see docs/security-followups.md for tenant-boundary tradeoffs)
  • 006 audit_log (append-only) + pending_changes
• Repos: spaces, projects, tasks, pages, refs, resources, source_docs, agents, conversations, messages, tags, links, attachments, audit, pending_changes — all accept an actor parameter on mutating ops and emit audit rows
• Real audit log with redaction of token, token_hash, password, api_key, secret, authorization keys (case-insensitive, nested)
• Capability check (canAct) with user / cron / worker / system → allow; agents tiered allow / suggest / deny based on capabilities + scopes
• Owner bearer-token auth middleware on all /api/*; /health is open
• Express server with /health (DB ping + version) and smoke /api/spaces
• systemd unit + deploy/push.sh rsync deploy + setup README
• 72 tests across 24 test files — all green

What's NOT here

• Routes for every entity (Plan 2)
• The Void 2.0 UI shell (Plan 2)
• Capture workers — Karakeep poll, YouTube, PDF/OCR, screenshots (Plan 3 + 4)
• MCP server for Claude / Ollama integration (Plan 5)
• Vaultwarden integration for credential storage (deferred, tracked in user memory)
• Migrations from Void 1.x / BookStack / Karakeep (Plan 7)

Known follow-ups

• docs/security-followups.md — three security-plugin findings on the polymorphic tables in migration 005 (HIGH: no space_id; MEDIUM: global tag namespace; MEDIUM: no cascade on parent delete). The polymorphic shape was an approved spec decision; decide tighten-vs-defer before Plan 1 is declared production-ready.
• lib/db/repos/audit_stub.js re-exports from audit.js for backwards compatibility with the 14 existing imports. Future repos should import from audit.js directly.
• void DB role currently has SUPERUSER for test extension creation. Acceptable for dev; revoke before exposing the DB beyond the LXC perimeter.
• vitest fileParallelism: false is a workaround for resetDb racing on DROP SCHEMA + CREATE EXTENSION. Tests run sequentially — ~20s for the full suite. Acceptable at current size.

How to verify

cd /project/src/void-v2

npm test
# Expect: 24 files, 72 tests, all passing.

npm run migrate
# Expect: silent success (migrations are idempotent — re-running is a no-op).

OWNER_TOKEN=test npm start &
sleep 1
curl -s localhost:3000/health
# {"ok":true,"db_ok":true,"version":"2.0.0-alpha.1"}
curl -s -H "Authorization: Bearer test" localhost:3000/api/spaces
# []
kill %1

Commit history

22 commits on main, each scoped to a single Plan 1 task. See git log --oneline.

Next: Plan 2 — Core REST API + Void UI shell