WIP! A BB-style forum, on the ATmosphere! We're still working... we'll be back soon when we have something to show off!
node typescript hono htmx atproto

docs: sync README and deployment guide with current codebase (#67)

- README: update packages/db to mention SQLite/LibSQL support alongside PostgreSQL
- README: add space.atbb.forum.board to the lexicon table (added by ATB-23)
- Deployment guide: fix stale plan doc path (moved to docs/plans/complete/)
- Deployment guide: update DATABASE_URL to document both PostgreSQL and SQLite formats
- Deployment guide: add SQLite overview paragraph to Section 4 Database Setup
- Deployment guide: update migration verification table list from 7 to 12 tables
- Deployment guide: bump version to 1.2, update date to 2026-02-26

authored by

Malpercio and committed by
GitHub
37aa9880 5c8511d3

+31 -15
+2 -1
README.md
··· 41 41 42 42 | Package | Description | 43 43 |---------|-------------| 44 - | [`packages/db`](packages/db) | Drizzle ORM schema and connection factory for PostgreSQL | 44 + | [`packages/db`](packages/db) | Drizzle ORM schema and connection factory (PostgreSQL and SQLite/LibSQL) | 45 45 | [`packages/lexicon`](packages/lexicon) | AT Proto lexicon schemas (YAML) and generated TypeScript types | 46 46 47 47 ## Getting Started ··· 128 128 | `space.atbb.forum.forum` | Forum DID | Forum metadata (name, description) | 129 129 | `space.atbb.forum.category` | Forum DID | Subforum / category definitions | 130 130 | `space.atbb.forum.role` | Forum DID | Role definitions with permission tokens | 131 + | `space.atbb.forum.board` | Forum DID | Board definitions within a category | 131 132 | `space.atbb.post` | User DID | Posts and replies (unified model) | 132 133 | `space.atbb.membership` | User DID | User's membership in a forum | 133 134 | `space.atbb.reaction` | User DID | Reactions on posts (like, upvote, etc.) |
+29 -14
docs/deployment-guide.md
··· 1 1 # atBB Deployment Guide 2 2 3 - **Version:** 1.1 4 - **Last Updated:** 2026-02-22 3 + **Version:** 1.2 4 + **Last Updated:** 2026-02-26 5 5 **Audience:** System administrators deploying atBB to production 6 6 7 7 > **Related Documentation:** 8 8 > - [docs/trust-model.md](trust-model.md) — Trust model for self-hosted deployment: what the AppView controls, user data guarantees, and security implications 9 - > - [docs/plans/2026-02-11-deployment-infrastructure-design.md](plans/2026-02-11-deployment-infrastructure-design.md) — Architectural decisions and design rationale behind this deployment approach 9 + > - [docs/plans/complete/2026-02-11-deployment-infrastructure-design.md](plans/complete/2026-02-11-deployment-infrastructure-design.md) — Architectural decisions and design rationale behind this deployment approach 10 10 11 11 ## Table of Contents 12 12 ··· 265 265 266 266 | Variable | Description | Example | 267 267 |----------|-------------|---------| 268 - | `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@host:5432/dbname?sslmode=require` | 268 + | `DATABASE_URL` | Database connection string (PostgreSQL or SQLite) | PostgreSQL: `postgresql://user:pass@host:5432/dbname?sslmode=require`; SQLite: `file:./atbb.db` | 269 269 | `FORUM_DID` | Forum's AT Protocol DID | `did:plc:abcdef1234567890` | 270 270 | `PDS_URL` | Personal Data Server URL | `https://bsky.social` | 271 271 | `FORUM_HANDLE` | Forum's AT Protocol handle | `forum.example.com` | ··· 373 373 --- 374 374 375 375 ## 4. Database Setup 376 + 377 + atBB supports two database backends: 378 + 379 + - **PostgreSQL** (recommended for production) — full-featured, suitable for multi-user/multi-server deployments 380 + - **SQLite/LibSQL** (lightweight alternative) — single-file database, ideal for small self-hosted forums. Use a `file:` prefix in `DATABASE_URL` (e.g. `file:./atbb.db`) and run the SQLite-specific migrations (`docker-compose.sqlite.yml` for Docker or set `database.type = "sqlite"` in the NixOS module). 381 + 382 + The rest of this section covers PostgreSQL provisioning. SQLite requires no separate server setup — just point `DATABASE_URL` at a file path. 376 383 377 384 ### PostgreSQL Provisioning 378 385 ··· 501 508 # List tables 502 509 \dt 503 510 504 - # Expected output: 505 - # Schema | Name | Type | Owner 506 - # --------+-------------------+-------+----------- 507 - # public | categories | table | atbb_user 508 - # public | firehose_cursor | table | atbb_user 509 - # public | forums | table | atbb_user 510 - # public | memberships | table | atbb_user 511 - # public | mod_actions | table | atbb_user 512 - # public | posts | table | atbb_user 513 - # public | users | table | atbb_user 511 + # Expected output (12 tables): 512 + # Schema | Name | Type | Owner 513 + # --------+-----------------------+-------+----------- 514 + # public | backfill_errors | table | atbb_user 515 + # public | backfill_progress | table | atbb_user 516 + # public | boards | table | atbb_user 517 + # public | categories | table | atbb_user 518 + # public | firehose_cursor | table | atbb_user 519 + # public | forums | table | atbb_user 520 + # public | memberships | table | atbb_user 521 + # public | mod_actions | table | atbb_user 522 + # public | posts | table | atbb_user 523 + # public | role_permissions | table | atbb_user 524 + # public | roles | table | atbb_user 525 + # public | users | table | atbb_user 514 526 ``` 515 527 516 528 ### Migration Troubleshooting ··· 1709 1721 ### Required Environment Variables 1710 1722 1711 1723 ```bash 1724 + # PostgreSQL (production recommended) 1712 1725 DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require 1726 + # SQLite (lightweight alternative) 1727 + # DATABASE_URL=file:./atbb.db 1713 1728 FORUM_DID=did:plc:xxxxxxxxxxxxx 1714 1729 PDS_URL=https://bsky.social 1715 1730 FORUM_HANDLE=forum.example.com