gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Self-Hosted PDS Reference Guide
2
3A reference guide for running your own AT Protocol Personal Data Server (PDS) alongside Barazo. This is **not required** for most deployments -- it covers advanced use cases only.
4
5## What is a PDS?
6
7A Personal Data Server (PDS) is where AT Protocol user accounts and data live. When someone creates a post, replies to a topic, or updates their profile on Barazo, that data is written to their PDS. Barazo's AppView then indexes it from the firehose.
8
9Think of it like email: the PDS is the mail server (stores your messages), while Barazo is the mail client (displays and organizes them).
10
11**By default, Barazo users create accounts on Bluesky's free PDS (`bsky.social`).** This works out of the box with no additional infrastructure. Existing AT Protocol users (Bluesky, Blacksky, Northsky, or any compliant PDS) sign in via OAuth automatically.
12
13## Do You Need a Self-Hosted PDS?
14
15**Most community admins do not.** Barazo works with any AT Protocol-compliant PDS via standard OAuth. Users bring their own identity.
16
17Self-hosting a PDS makes sense in specific scenarios:
18
19| Use case | Why self-host |
20|----------|--------------|
21| **Data sovereignty** | Keep all user data on infrastructure you control |
22| **Air-gapped environments** | Network-restricted deployments that cannot reach `bsky.social` |
23| **Organizational accounts** | Issue AT Protocol identities under your own domain (e.g., `@jay.yourorg.com`) |
24| **Regulatory compliance** | Data residency requirements that prohibit US-hosted PDS providers |
25
26If none of these apply, use the default setup. Users sign up via Bluesky's PDS and it works.
27
28## How Barazo Relates to a PDS
29
30Understanding the data flow helps clarify why PDS hosting is separate from Barazo:
31
32```
33User's PDS (bsky.social or self-hosted)
34 └── Stores user records (posts, replies, profiles)
35 │
36 ▼
37AT Protocol Relay (bsky.network)
38 └── Aggregates updates from all PDSs
39 │
40 ▼
41Barazo AppView (your server)
42 └── Indexes forum.barazo.* records
43 └── Serves the forum UI
44```
45
46- **PDS** = source of truth for user data
47- **Relay** = transport layer that broadcasts changes
48- **AppView (Barazo)** = read index that presents the forum
49
50Barazo never stores user content as the primary copy. If the AppView database is lost, it can be rebuilt from the firehose. If a user's PDS is lost, their data is gone (which is why PDS backup matters).
51
52## Setting Up a Self-Hosted PDS
53
54Barazo does not provide PDS software. The AT Protocol team maintains the official PDS implementation.
55
56**Official documentation:** [atproto.com/guides/self-hosting](https://atproto.com/guides/self-hosting)
57
58### Prerequisites
59
60- A domain name (e.g., `pds.yourorg.com`)
61- A server with a public IP address (separate from or co-located with your Barazo server)
62- DNS records configured for your PDS domain
63- SSL certificate (the official PDS installer handles this via Let's Encrypt)
64
65### Key Steps (Summary)
66
67The official installer script handles most of the setup. At a high level:
68
691. Point a DNS A record to your server
702. Run the official PDS installer script
713. Create user accounts on your PDS (via `pdsadmin`)
724. Users sign into Barazo using their PDS-hosted identity via OAuth
73
74For detailed instructions, follow the official guide linked above. Do not rely on this summary -- the AT Protocol team updates their installer as the protocol evolves.
75
76## Configuring Barazo for a Custom PDS
77
78**No Barazo-specific configuration is needed.** AT Protocol OAuth handles PDS discovery automatically:
79
801. A user enters their handle (e.g., `@jay.yourorg.com`)
812. Barazo resolves the handle to a DID
823. The DID document points to the user's PDS
834. OAuth proceeds with that PDS
84
85This works identically whether the user is on `bsky.social`, a third-party PDS, or your self-hosted PDS. The `RELAY_URL` in your Barazo `.env` controls which relay the AppView subscribes to for firehose events -- this is independent of where users' PDSs are hosted.
86
87### Ensuring Your PDS Records Reach Barazo
88
89For Barazo to index posts from your self-hosted PDS, the PDS must be connected to a relay that Barazo subscribes to. In the default configuration:
90
91- Barazo subscribes to `wss://bsky.network` (the Bluesky relay)
92- Your self-hosted PDS must be registered with this relay to have its records indexed
93
94If your PDS is not connected to the Bluesky relay (e.g., air-gapped environments), you would need to run your own relay and point Barazo's `RELAY_URL` to it. This is an advanced configuration outside the scope of this guide.
95
96## Limitations and Trade-offs
97
98### Self-hosted PDS vs. bsky.social
99
100| Aspect | bsky.social | Self-hosted PDS |
101|--------|------------|-----------------|
102| **Setup effort** | None (automatic) | Requires server, domain, DNS, maintenance |
103| **Cost** | Free | Server costs + ongoing maintenance |
104| **Data location** | US (Bluesky's infrastructure) | Your infrastructure, your jurisdiction |
105| **Account recovery** | Bluesky handles it | You are responsible |
106| **Uptime** | Managed by Bluesky team | Your responsibility |
107| **Custom handles** | `*.bsky.social` or custom domain via DNS | Full control over handle namespace |
108| **Relay connectivity** | Automatic | Must register with a relay |
109| **Protocol updates** | Automatic | You manage PDS software updates |
110
111### Important Considerations
112
113- **Backup is your responsibility.** The PDS stores the authoritative copy of user data. If your PDS loses data, it cannot be recovered from Barazo (the AppView only holds an index).
114- **PDS software updates** are released by the AT Protocol team. You must keep your PDS updated to remain compatible with the network.
115- **Handle resolution** requires proper DNS configuration. If your DNS goes down, users cannot sign in.
116- **One PDS per user.** A user's AT Protocol identity is tied to one PDS at a time. They can migrate between PDSs, but cannot use multiple simultaneously.
117
118## Further Reading
119
120- [AT Protocol Self-Hosting Guide](https://atproto.com/guides/self-hosting) -- official PDS setup instructions
121- [AT Protocol Specification](https://atproto.com/specs) -- protocol details
122- [Barazo Installation Guide](installation.md) -- setting up Barazo itself
123- [Barazo Configuration Reference](configuration.md) -- all environment variables