sullen.net
Fork of official Bluesky PDS (Personal Data Server).
Merge pull request #278 from bluesky-social/vps-install-edits
minor VPS install edits
authored by
Alex Garnett
and committed by
GitHub
4247909e
e176986e
+67
-24
README.md
+67
-24
README.md
···
17
- [What is AT Protocol?](#what-is-at-protocol)
18
- [Where is the code?](#where-is-the-code)
19
- [What is the current status of federation?](#what-is-the-current-status-of-federation)
20
-
- [Self-hosting PDS](#self-hosting-pds)
21
-
- [Preparation for self-hosting PDS](#preparation-for-self-hosting-pds)
22
- [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https)
23
- [Configure DNS for your domain](#configure-dns-for-your-domain)
24
- [Check that DNS is working as expected](#check-that-dns-is-working-as-expected)
25
-
- [Installer on Ubuntu 20.04/22.04/24.04 and Debian 11/12](#installer-on-ubuntu-200422042404-and-debian-1112)
26
- [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible)
27
- [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin)
28
- [Creating an account using an invite code](#creating-an-account-using-an-invite-code)
···
56
57
### What is the current status of federation?
58
59
-
As of Spring 2024, the AT Protocol network is open to federation!
60
61
✅ Federated domain handles (e.g. `@nytimes.com`)
62
···
70
71
✅ Federated moderation (labeling)
72
73
-
## Self-hosting PDS
74
75
Self-hosting a Bluesky PDS means running your own Personal Data Server that is capable of federating with the wider Bluesky social network.
76
77
-
### Preparation for self-hosting PDS
78
79
-
Launch a server on any cloud provider, [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices.
80
81
Ensure that you can ssh to your server and have root access.
82
···
135
136
These should all return your server's public IP.
137
138
-
### Installer on Ubuntu 20.04/22.04/24.04 and Debian 11/12
139
140
-
On your server via ssh, download the installer script using wget:
141
142
```bash
143
-
wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
144
```
145
146
-
or download it using curl:
147
148
```bash
149
-
curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh
150
```
151
152
-
And then run the installer using bash:
153
154
-
```bash
155
-
sudo bash installer.sh
156
```
157
158
### Verifying that your PDS is online and accessible
159
160
> [!TIP]
161
-
> 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.
162
163
-
You can check if your server is online and healthy by requesting the healthcheck endpoint.
164
165
-
You can visit `https://example.com/xrpc/_health` in your browser. You should see a JSON response with a version, like:
166
167
```
168
{"version":"0.2.2-beta.2"}
···
174
wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0"
175
```
176
177
-
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.
178
179
### Creating an account using pdsadmin
180
181
-
Using ssh on your server, use `pdsadmin` to create an account if you haven't already.
182
183
```bash
184
sudo pdsadmin account create
···
186
187
### Creating an account using an invite code
188
189
-
Using ssh on your server, use `pdsadmin` to create an invite code.
190
191
```bash
192
sudo pdsadmin create-invite-code
···
210
211
To be able to verify users' email addresses and send other emails, you need to set up an SMTP server.
212
213
-
One way to do this is to use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices.
214
215
-
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):
216
217
```
218
PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:465/
···
265
266
### Updating your PDS
267
268
-
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.
269
270
```bash
271
sudo pdsadmin update
···
17
- [What is AT Protocol?](#what-is-at-protocol)
18
- [Where is the code?](#where-is-the-code)
19
- [What is the current status of federation?](#what-is-the-current-status-of-federation)
20
+
- [Self-hosting a PDS](#self-hosting-a-pds)
21
+
- [Deploying a PDS onto a VPS](#deploying-a-pds-onto-a-vps)
22
- [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https)
23
- [Configure DNS for your domain](#configure-dns-for-your-domain)
24
- [Check that DNS is working as expected](#check-that-dns-is-working-as-expected)
25
+
- [Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13](#installing-on-ubuntu-200422042404-and-debian-111213)
26
- [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible)
27
- [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin)
28
- [Creating an account using an invite code](#creating-an-account-using-an-invite-code)
···
56
57
### What is the current status of federation?
58
59
+
The AT Protocol network is open to federation!
60
61
✅ Federated domain handles (e.g. `@nytimes.com`)
62
···
70
71
✅ Federated moderation (labeling)
72
73
+
## Self-hosting a PDS
74
75
Self-hosting a Bluesky PDS means running your own Personal Data Server that is capable of federating with the wider Bluesky social network.
76
77
+
### Deploying a PDS onto a VPS
78
79
+
This README provides instructions for deploying a PDS using our install script onto a Virtual Private Server. [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices for VPS hosting.
80
81
Ensure that you can ssh to your server and have root access.
82
···
135
136
These should all return your server's public IP.
137
138
+
### Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13
139
+
140
+
Note that this script assumes a relatively "fresh" VPS that is not also concurrently hosting a web server or anything else on port 80/443. If you intend to run a PDS alongside an existing webserver on the same VPS, you will not want to use this install script.
141
142
+
On your server, download the install script using `curl`:
143
144
```bash
145
+
curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh > installer.sh
146
```
147
148
+
And then run the installer using `bash`. You will need `sudo` permissions to continue:
149
150
```bash
151
+
sudo bash installer.sh
152
+
```
153
+
154
+
The install script is interactive and will prompt for input during the install process. You will need to provide your public DNS address, an admin email address (which does not need to be from the same domain), and be prompted to create a PDS user account with its own email address and handle. If you plan to reuse an existing AT handle, you can skip user account creation, though if it is your first time deploying a PDS you may want to create an account using your domain like `account.your-domain.net` for testing purposes.
155
+
156
+
Upon completion of a successful installation, you'll receive output similar to the following:
157
+
158
+
```
159
+
========================================================================
160
+
PDS installation successful!
161
+
------------------------------------------------------------------------
162
+
163
+
Check service status : sudo systemctl status pds
164
+
Watch service logs : sudo docker logs -f pds
165
+
Backup service data : /pds
166
+
PDS Admin command : pdsadmin
167
+
168
+
Required Firewall Ports
169
+
------------------------------------------------------------------------
170
+
Service Direction Port Protocol Source
171
+
------- --------- ---- -------- ----------------------
172
+
HTTP TLS verification Inbound 80 TCP Any
173
+
HTTP Control Panel Inbound 443 TCP Any
174
+
175
+
Required DNS entries
176
+
------------------------------------------------------------------------
177
+
Name Type Value
178
+
------- --------- ---------------
179
+
your-domain.net A your-ip-address
180
+
*.your-domain.net A your-ip-address
181
+
182
+
Detected public IP of this server: your-ip-address
183
+
184
+
To see pdsadmin commands, run "pdsadmin help"
185
+
186
+
========================================================================
187
```
188
189
+
And, following account creation:
190
191
+
```
192
+
Account created successfully!
193
+
-----------------------------
194
+
Handle : handle.your-domain.net
195
+
DID : did:plc:your-did
196
+
Password : your-password
197
+
-----------------------------
198
+
Save this password, it will not be displayed again.
199
```
200
201
### Verifying that your PDS is online and accessible
202
203
> [!TIP]
204
+
> The most common problems with getting PDS content consumed in the live network usually result from users trying to port the provided Caddy configuration to Nginx, Apache, or other reverse proxies. Getting TLS certificates, WebSockets, and virtual server names provisioned can be challenging. We are not currently providing tech support for other configurations.
205
206
+
After installation, your PDS should be live and accessible on the web. You can check if your server is online and healthy by making a request to `https://your-domain.net/xrpc/_health` (the healthcheck endpoint). You should see a JSON response with a version, like:
207
208
+
Visit `https://your-domain.net/xrpc/_health` in your browser. You should see a JSON response with a version, like:
209
210
```
211
{"version":"0.2.2-beta.2"}
···
217
wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0"
218
```
219
220
+
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 immediately post-installation.
221
222
### Creating an account using pdsadmin
223
224
+
You'll now have access to some additional command line tools on this server. Use `pdsadmin` to create an account if you haven't already:
225
226
```bash
227
sudo pdsadmin account create
···
229
230
### Creating an account using an invite code
231
232
+
If needed, use `pdsadmin` to create an invite code:
233
234
```bash
235
sudo pdsadmin create-invite-code
···
253
254
To be able to verify users' email addresses and send other emails, you need to set up an SMTP server.
255
256
+
As an alternative to running your own SMTP server, you can use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices.
257
258
+
Create an account and API key on an email service, ensure your server allows access on the required ports, and then you can add these configuration variables to `/pds/pds.env` on your server (example with Resend):
259
260
```
261
PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:465/
···
308
309
### Updating your PDS
310
311
+
It is recommended that you keep your PDS up to date with new versions. You can use the `pdsadmin` tool to update your PDS.
312
313
```bash
314
sudo pdsadmin update
+4
-1
installer.sh
+4
-1
installer.sh
···
105
elif [[ "${DISTRIB_CODENAME}" == "bookworm" ]]; then
106
SUPPORTED_OS="true"
107
echo "* Detected supported distribution Debian 12"
108
fi
109
fi
110
111
if [[ "${SUPPORTED_OS}" != "true" ]]; then
112
-
echo "Sorry, only Ubuntu 20.04, 22.04, 24.04, Debian 11 and Debian 12 are supported by this installer. Exiting..."
113
exit 1
114
fi
115
···
105
elif [[ "${DISTRIB_CODENAME}" == "bookworm" ]]; then
106
SUPPORTED_OS="true"
107
echo "* Detected supported distribution Debian 12"
108
+
elif [[ "${DISTRIB_CODENAME}" == "trixie" ]]; then
109
+
SUPPORTED_OS="true"
110
+
echo "* Detected supported distribution Debian 13"
111
fi
112
fi
113
114
if [[ "${SUPPORTED_OS}" != "true" ]]; then
115
+
echo "Sorry, only Ubuntu 20.04, 22.04, 24.04, and Debian 11, 12, and 13 are supported by this installer. Exiting..."
116
exit 1
117
fi
118