/ README.md
README.md
1 # PDS 2 3 Welcome to the repository for the official Bluesky PDS (Personal Data Server). This repository includes container images and documentation designed to assist technical people with hosting a Bluesky PDS. 4 5 Head over to the [AT Protocol PDS Admins Discord](https://discord.gg/e7hpHxRfBP) to chat with other folks hosting instances and get important updates about the PDS distribution! 6 7 ## Table of Contents 8 9 <!-- markdown-toc -i README.md --> 10 11 <!-- toc --> 12 13 - [FAQ](#faq) 14 * [What is Bluesky?](#what-is-bluesky) 15 * [What is AT Protocol?](#what-is-at-protocol) 16 * [Where is the code?](#where-is-the-code) 17 * [What is the current status of federation?](#what-is-the-current-status-of-federation) 18 - [Self-hosting PDS](#self-hosting-pds) 19 * [Preparation for self-hosting PDS](#preparation-for-self-hosting-pds) 20 * [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https) 21 * [Configure DNS for your domain](#configure-dns-for-your-domain) 22 * [Check that DNS is working as expected](#check-that-dns-is-working-as-expected) 23 * [Installer on Ubuntu 20.04/22.04 and Debian 11/12](#installer-on-ubuntu-20042204-and-debian-1112) 24 * [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible) 25 * [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin) 26 * [Creating an account using an invite code](#creating-an-account-using-an-invite-code) 27 * [Using the Bluesky app with your PDS](#using-the-bluesky-app-with-your-pds) 28 * [Setting up SMTP](#setting-up-smtp) 29 * [Updating your PDS](#updating-your-pds) 30 31 <!-- tocstop --> 32 33 ## FAQ 34 35 ### What is Bluesky? 36 37 Bluesky is a social media application built on AT Protocol. 38 39 Please visit the [Bluesky website](https://bsky.social/) for more information. 40 41 ### What is AT Protocol? 42 43 The Authenticated Transfer Protocol, aka atproto, is a protocol for large-scale distributed social applications. 44 45 Please visit the [AT Protocol docs](https://atproto.com/guides/overview) for additional information. 46 47 ### Where is the code? 48 49 * [TypeScript code](https://github.com/bluesky-social/atproto/tree/main/packages/pds) 50 * [Go code](https://github.com/bluesky-social/indigo) 51 52 ### What is the current status of federation? 53 54 As of Spring 2024, the AT Protocol network is open to federation! 55 56 ✅ Federated domain handles (e.g. `@nytimes.com`) 57 58 ✅ Federated feed generators (custom algorithms) 59 60 ✅ Federated relays (event firehose) 61 62 ✅ Federated app views (API service) 63 64 ✅ Federated data (PDS hosting) 65 66 ✅ Federated moderation (labeling) 67 68 ## Self-hosting PDS 69 70 Self-hosting a Bluesky PDS means running your own Personal Data Server that is capable of federating with the wider Bluesky social network. 71 72 ### Preparation for self-hosting PDS 73 74 Launch a server on any cloud provider, [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices. 75 76 Ensure that you can ssh to your server and have root access. 77 78 **Server Requirements** 79 * Public IPv4 address 80 * Public DNS name 81 * Public inbound internet access permitted on port 80/tcp and 443/tcp 82 83 **Server Recommendations** 84 | | | 85 | ---------------- | ------------ | 86 | Operating System | Ubuntu 22.04 | 87 | Memory (RAM) | 1 GB | 88 | CPU Cores | 1 | 89 | Storage | 20 GB SSD | 90 | Architectures | amd64, arm64 | 91 | Number of users | 1-20 | 92 93 **Note:** It is a good security practice to restrict inbound ssh access (port 22/tcp) to your own computer's public IP address. You can check your current public IP address using [ifconfig.me](https://ifconfig.me/). 94 95 ### Open your cloud firewall for HTTP and HTTPS 96 97 One of the most common sources of misconfiguration is not opening firewall ports correctly. Please be sure to double check this step. 98 99 In your cloud provider's console, the following ports should be open to inbound access from the public internet. 100 101 * 80/tcp (Used only for TLS certification verification) 102 * 443/tcp (Used for all application requests) 103 104 **Note:** there is no need to set up TLS or redirect requests from port 80 to 443 because the Caddy web server, included in the Docker compose file, will handle this for you. 105 106 ### Configure DNS for your domain 107 108 From your DNS provider's control panel, set up a domain with records pointing to your server. 109 110 | Name | Type | Value | TTL | 111 | --------------- | ---- | ------------- | --- | 112 | `example.com` | `A` | `12.34.56.78` | 600 | 113 | `*.example.com` | `A` | `12.34.56.78` | 600 | 114 115 **Note:** 116 * Replace `example.com` with your domain name. 117 * Replace `12.34.56.78` with your server's IP address. 118 * Some providers may use the `@` symbol to represent the root of your domain. 119 * The wildcard record is required when allowing users to create new accounts on your PDS. 120 * The TTL can be anything but 600 (10 minutes) is reasonable 121 122 ### Check that DNS is working as expected 123 124 Use a service like [DNS Checker](https://dnschecker.org/) to verify that you can resolve domain names. 125 126 Examples to check (record type `A`): 127 * `example.com` 128 * `random.example.com` 129 * `test123.example.com` 130 131 These should all return your server's public IP. 132 133 ### Installer on Ubuntu 20.04/22.04 and Debian 11/12 134 135 On your server via ssh, download the installer script using wget: 136 137 ```bash 138 wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh 139 ``` 140 141 or download it using curl: 142 143 ```bash 144 curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh 145 ``` 146 147 And then run the installer using bash: 148 149 ```bash 150 sudo bash installer.sh 151 ``` 152 153 ### Verifying that your PDS is online and accessible 154 155 > [!TIP] 156 > The most common problems with getting PDS content consumed in the live network are when folks substitute the provided Caddy configuration for nginx, apache, or similar reverse proxies. Getting TLS certificates, WebSockets, and virtual server names all correct can be tricky. We are not currently providing tech support for other configurations. 157 158 You can check if your server is online and healthy by requesting the healthcheck endpoint. 159 160 You can visit `https://example.com/xrpc/_health` in your browser. You should see a JSON response with a version, like: 161 162 ``` 163 {"version":"0.2.2-beta.2"} 164 ``` 165 166 You'll also need to check that WebSockets are working, for the rest of the network to pick up content from your PDS. You can test by installing a tool like `wsdump` and running a command like: 167 168 ```bash 169 wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0" 170 ``` 171 172 Note that there will be no events output on the WebSocket until they are created in the PDS, so the above command may continue to run with no output if things are configured successfully. 173 174 ### Creating an account using pdsadmin 175 176 Using ssh on your server, use `pdsadmin` to create an account if you haven't already. 177 178 ```bash 179 sudo pdsadmin account create 180 ``` 181 182 ### Creating an account using an invite code 183 184 Using ssh on your server, use `pdsadmin` to create an invite code. 185 186 ```bash 187 sudo pdsadmin create-invite-code 188 ``` 189 190 When creating an account using the app, enter this invite code. 191 192 ### Using the Bluesky app with your PDS 193 194 You can use the Bluesky app to connect to your PDS. 195 196 1. Get the Bluesky app 197 * [Bluesky for Web](https://bsky.app/) 198 * [Bluesky for iPhone](https://apps.apple.com/us/app/bluesky-social/id6444370199) 199 * [Bluesky for Android](https://play.google.com/store/apps/details?id=xyz.blueskyweb.app) 200 1. Enter the URL of your PDS (e.g. `https://example.com/`) 201 202 _Note: because the subdomain TLS certificate is created on-demand, it may take 10-30s for your handle to be accessible. If you aren't seeing your first post/profile, wait 30s and try to make another post._ 203 204 ### Setting up SMTP 205 206 To be able to verify users' email addresses and send other emails, you need to set up an SMTP server. 207 208 One way to do this is to use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices. 209 210 Create an account and API key on an email service, ensure your server allows access on the required ports, and set these variables in `/pds/pds.env` (example with Resend): 211 212 ``` 213 PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:465/ 214 PDS_EMAIL_FROM_ADDRESS=admin@your.domain 215 ``` 216 217 _Note: Your PDS will need to be restarted with those variables. This varies depending on your setup. If you followed this installation guide, run `systemctl restart pds`. You might need to restart the server or recreate the container, depending on what you are using._ 218 219 ### Updating your PDS 220 221 It is recommended that you keep your PDS up to date with new versions, otherwise things may break. You can use the `pdsadmin` tool to update your PDS. 222 223 ```bash 224 sudo pdsadmin update 225 ``` 226 227 ## License 228 229 This project is dual-licensed under MIT and Apache 2.0 terms: 230 231 - MIT license ([LICENSE-MIT.txt](https://github.com/bluesky-social/pds/blob/main/LICENSE-MIT.txt) or http://opensource.org/licenses/MIT) 232 - Apache License, Version 2.0, ([LICENSE-APACHE.txt](https://github.com/bluesky-social/pds/blob/main/LICENSE-APACHE.txt) or http://www.apache.org/licenses/LICENSE-2.0) 233 234 Downstream projects and end users may choose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.