Document Pubky 0.8 Postgres requirements

src/content/docs/architecture.md

@@ -110,7 +110,7 @@ sequenceDiagram
 
 ### Storage Layer
 
-**[Homeservers](/explore/pubkycore/homeserver/)** store user data in a key-value format over HTTP/HTTPS.
+**[Homeservers](/explore/pubkycore/homeserver/)** store user data as files addressed by paths over HTTP/HTTPS.
 
 **Architecture:**
 
@@ -119,11 +119,11 @@ flowchart LR
     User1[User 1] --> HS1[Homeserver A]
     User2[User 2] --> HS1
     User3[User 3] --> HS2[Homeserver B]
-    User4[User 4] --> HS3[Homeserver C]
 
-    HS1 --> DB1[(PostgreSQL)]
-    HS2 --> DB2[(LMDB)]
-    HS3 --> DB3[(Files)]
+    HS1 --> FS1[(User files)]
+    HS1 --> PG1[(PostgreSQL metadata)]
+    HS2 --> FS2[(User files)]
+    HS2 --> PG2[(PostgreSQL metadata)]
 ```
 
 **Key Properties:**

src/content/docs/contributing.md

@@ -190,7 +190,7 @@ cargo build
 # Run tests
 cargo test
 
-# Run homeserver locally
+# Run homeserver locally (requires PostgreSQL and database_url in config)
 cargo run --bin pubky-homeserver
 
 # Format code

src/content/docs/explore/pubkycore/api.md

@@ -356,7 +356,7 @@ Returns the user count, the disabled-user count, total disk usage in MB, signup-
   "public_key": "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo",
   "pkarr_pubky_address": null,
   "pkarr_icann_domain": "homeserver.example.com",
-  "version": "0.7.0"
+  "version": "0.8.0"
 }
 ```
 

src/content/docs/explore/pubkycore/homeserver.md

@@ -44,7 +44,7 @@ See [Security Model](/explore/pubkycore/security-model/) for the full trust anal
 
 > **Note:** Production deployment guides are not yet available. Easy deployment packages (Umbrel, apt, docker, start9) are under development.
 
-For local development and testing:
+For local development and testing, start PostgreSQL and configure `database_url`, then run:
 
 ```bash
 cargo run -p pubky-homeserver
@@ -58,7 +58,7 @@ cargo run -p pubky-testnet
 
 ### Embedded Postgres
 
-Since v0.7.0, the testnet supports an optional embedded Postgres mode via the `embedded-postgres` feature flag. This allows fully self-contained test environments without requiring an external database:
+The testnet can start embedded Postgres via the `embedded-postgres` feature flag. This keeps local test environments self-contained without requiring an external database:
 
 ```bash
 cargo run -p pubky-testnet --features embedded-postgres

src/content/docs/explore/pubkycore/introduction.md

@@ -37,7 +37,7 @@ A production-ready server application that:
 - Provides RESTful HTTP API
 - Handles authentication and sessions
 - Publishes to [PKARR](/explore/pubkycore/pkarr/introduction/) for discovery
-- Supports multiple persistence backends (Files, LMDB, SQL)
+- Stores user files separately from PostgreSQL-backed homeserver metadata
 - Includes admin and metrics endpoints
 
 ### 3. SDK (Software Development Kit)
@@ -82,7 +82,7 @@ Pubky Core's distributed architecture provides user autonomy through credible ex
 - **Docker support**: Easy deployment and testing
 
 ### Production-Ready
-- **Multiple persistence backends**: Choose between Files, LMDB, or SQL
+- **PostgreSQL-backed metadata**: Homeservers store user files separately while PostgreSQL tracks users, quotas, sessions, and events
 - **Rate limiting**: Built-in DDoS protection
 - **Metrics and monitoring**: Prometheus-compatible metrics
 - **Admin API**: Server management and diagnostics
@@ -147,10 +147,11 @@ See [SDK Documentation](/explore/pubkycore/sdk/) for complete guides.
 ### Run Local Homeserver
 
 **Using Cargo:**
+Start PostgreSQL and configure `database_url` before running a standalone Homeserver:
 ```bash
 git clone https://github.com/pubky/pubky-core
 cd pubky-core/pubky-homeserver
-cargo run
+cargo run -- --data-dir=~/.pubky
 ```
 
 **Using Docker:**
@@ -257,7 +258,7 @@ For [Synonym](https://synonym.to/) as lead of this project, the goal is to:
 - ✅ JavaScript/WASM bindings stable
 - ✅ Authentication system complete
 - ✅ Event streaming SDK (SSE-based, single and multi-user)
-- ✅ Multiple persistence backends
+- ✅ User file storage on Homeservers, with PostgreSQL-backed metadata
 
 **Active Development:**
 - 🚧 Mobile native bindings (iOS/Android)

src/content/docs/explore/pubkycore/sdk.md

@@ -322,8 +322,8 @@ For development, run a local Homeserver:
 git clone https://github.com/pubky/pubky-core
 cd pubky-core
 
-# Run testnet
-cargo run --bin pubky-testnet
+# Run testnet with embedded PostgreSQL
+cargo run -p pubky-testnet --features embedded-postgres
 ```
 
 Then connect your app to `http://localhost:15411`.

src/content/docs/explore/technologies/pubky-cli.md

@@ -213,7 +213,7 @@ echo "User onboarded successfully!"
 
 Test Homeserver functionality without building custom clients:
 ```bash
-# Start local homeserver
+# Start local homeserver (requires PostgreSQL and database_url in config)
 cargo run -p pubky-homeserver -- --data-dir ~/.pubky
 
 # Test with CLI

src/content/docs/getting-started.md

@@ -113,11 +113,11 @@ cd ios && pod install  # iOS only
 
 See the [Pubky Docker documentation](/explore/technologies/pubky-docker/) for setup instructions, port mappings, and configuration options.
 
-**Alternative**: Run just a Homeserver:
+**Alternative**: Run just a Homeserver. Start PostgreSQL and configure `database_url` first; see the [Homeserver documentation](/explore/pubkycore/homeserver/) for details:
 ```bash
 git clone https://github.com/pubky/pubky-core
 cd pubky-core/pubky-homeserver
-cargo run
+cargo run -- --data-dir=~/.pubky
 ```
 
 ### Step 3: Build Your First App

src/content/docs/glossary.md

@@ -39,7 +39,7 @@ Protocol for encrypting DNS queries using HTTPS, preventing surveillance and tam
 ## H
 
 **[Homeserver](/explore/pubkycore/homeserver/)**
-A web server that stores user data in a key-value format. Users can run their own or choose any provider. Data is stored per public key and accessed via HTTP/HTTPS.
+A web server that stores user data as files addressed by paths. Internally, PostgreSQL tracks metadata such as users, quotas, sessions, and events. Users can run their own or choose any provider. Data is stored per public key and accessed via HTTP/HTTPS.
 
 **[Homegate](/explore/technologies/homegate/)**
 A signup verification service for Homeservers, providing SMS and Lightning Network payment verification to prevent spam while preserving privacy.