this repo has no description
lewis.moe
1# BSPDS, a Personal Data Server
2
3A production-grade Personal Data Server (PDS) implementation for the AT Protocol.
4
5Uses PostgreSQL instead of SQLite, S3-compatible blob storage, and is designed to be a complete drop-in replacement for Bluesky's reference PDS implementation.
6
7## Features
8
9- Full AT Protocol support, all `com.atproto.*` endpoints implemented
10- OAuth 2.1 Provider. PKCE, DPoP, Pushed Authorization Requests
11- PostgreSQL, prod-ready database backend
12- S3-compatible object storage for blobs; works with AWS S3, UpCloud object storage, self-hosted MinIO, etc.
13- WebSocket `subscribeRepos` endpoint for real-time sync
14- Crawler notifications via `requestCrawl`
15- Multi-channel notifications: email, discord, telegram, signal
16- Per-IP rate limiting on sensitive endpoints
17- Built-in web UI for account management
18
19## Running Locally
20
21Requires Rust installed locally.
22
23Run PostgreSQL and S3-compatible object store (e.g., with podman/docker):
24
25```bash
26podman compose up db objsto -d
27```
28
29Run the PDS:
30
31```bash
32just run
33```
34
35## Configuration
36
37### Required
38
39| Variable | Description |
40|----------|-------------|
41| `DATABASE_URL` | PostgreSQL connection string |
42| `S3_BUCKET` | Blob storage bucket name |
43| `S3_ENDPOINT` | S3 endpoint URL (for MinIO, etc.) |
44| `AWS_ACCESS_KEY_ID` | S3 credentials |
45| `AWS_SECRET_ACCESS_KEY` | S3 credentials |
46| `AWS_REGION` | S3 region |
47| `PDS_HOSTNAME` | Public hostname of this PDS |
48| `JWT_SECRET` | Secret for OAuth token signing (HS256) |
49| `KEY_ENCRYPTION_KEY` | Key for encrypting user signing keys (AES-256-GCM) |
50
51### Optional
52
53| Variable | Description |
54|----------|-------------|
55| `APPVIEW_URL` | Appview URL to proxy unimplemented endpoints to |
56| `CRAWLERS` | Comma-separated list of relay URLs to notify via `requestCrawl` |
57
58### Notifications
59
60At least one channel should be configured for user notifications (password reset, email verification, etc.):
61
62| Variable | Description |
63|----------|-------------|
64| `MAIL_FROM_ADDRESS` | Email sender address (enables email via sendmail) |
65| `MAIL_FROM_NAME` | Email sender name (default: "BSPDS") |
66| `SENDMAIL_PATH` | Path to sendmail binary (default: /usr/sbin/sendmail) |
67| `DISCORD_WEBHOOK_URL` | Discord webhook URL for notifications |
68| `TELEGRAM_BOT_TOKEN` | Telegram bot token for notifications |
69| `SIGNAL_CLI_PATH` | Path to signal-cli binary |
70| `SIGNAL_SENDER_NUMBER` | Signal sender phone number (+1234567890 format) |
71
72## Development
73
74```bash
75just # Show available commands
76just test # Run tests (auto-starts postgres/minio, runs nextest)
77just lint # Clippy + fmt check
78just db-reset # Drop and recreate local database
79```
80
81## Web UI
82
83BSPDS includes a built-in web frontend for users to manage their accounts. Users can:
84
85- Sign in and register new accounts
86- Manage app passwords
87- View and create invite codes
88- Update email and handle
89- Configure notification preferences
90- Browse their repository data
91
92The frontend is built with svelte and deno, and is served directly by the PDS.
93
94```bash
95just frontend-dev # Run frontend dev server
96just frontend-build # Build for production
97just frontend-test # Run frontend tests
98```
99
100## Project Structure
101
102```
103src/
104 main.rs Server entrypoint
105 lib.rs Router setup
106 state.rs AppState (db pool, stores, rate limiters, circuit breakers)
107 api/ XRPC handlers organized by namespace
108 auth/ JWT authentication (ES256K per-user keys)
109 oauth/ OAuth 2.1 provider (HS256 server-wide)
110 repo/ PostgreSQL block store
111 storage/ S3 blob storage
112 sync/ Firehose, CAR export, crawler notifications
113 notifications/ Multi-channel notification service
114 plc/ PLC directory client
115 circuit_breaker/ Circuit breaker for external services
116 rate_limit/ Per-IP rate limiting
117frontend/ Svelte web UI (deno)
118tests/ Integration tests
119migrations/ SQLx migrations
120```
121
122## License
123
124TBD