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
17
- [What is AT Protocol?](#what-is-at-protocol)
18
18
- [Where is the code?](#where-is-the-code)
19
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)
20
+
- [Self-hosting a PDS](#self-hosting-a-pds)
21
+
- [Deploying a PDS onto a VPS](#deploying-a-pds-onto-a-vps)
22
22
- [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https)
23
23
- [Configure DNS for your domain](#configure-dns-for-your-domain)
24
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)
25
+
- [Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13](#installing-on-ubuntu-200422042404-and-debian-111213)
26
26
- [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible)
27
27
- [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin)
28
28
- [Creating an account using an invite code](#creating-an-account-using-an-invite-code)
···
56
56
57
57
### What is the current status of federation?
58
58
59
-
As of Spring 2024, the AT Protocol network is open to federation!
59
+
The AT Protocol network is open to federation!
60
60
61
61
✅ Federated domain handles (e.g. `@nytimes.com`)
62
62
···
70
70
71
71
✅ Federated moderation (labeling)
72
72
73
-
## Self-hosting PDS
73
+
## Self-hosting a PDS
74
74
75
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
76
77
-
### Preparation for self-hosting PDS
77
+
### Deploying a PDS onto a VPS
78
78
79
-
Launch a server on any cloud provider, [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices.
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
80
81
81
Ensure that you can ssh to your server and have root access.
82
82
···
135
135
136
136
These should all return your server's public IP.
137
137
138
-
### Installer on Ubuntu 20.04/22.04/24.04 and Debian 11/12
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.
139
141
140
-
On your server via ssh, download the installer script using wget:
142
+
On your server, download the install script using `curl`:
141
143
142
144
```bash
143
-
wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
145
+
curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh > installer.sh
144
146
```
145
147
146
-
or download it using curl:
148
+
And then run the installer using `bash`. You will need `sudo` permissions to continue:
147
149
148
150
```bash
149
-
curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh
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
+
========================================================================
150
187
```
151
188
152
-
And then run the installer using bash:
189
+
And, following account creation:
153
190
154
-
```bash
155
-
sudo bash installer.sh
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.
156
199
```
157
200
158
201
### Verifying that your PDS is online and accessible
159
202
160
203
> [!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.
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.
162
205
163
-
You can check if your server is online and healthy by requesting the healthcheck endpoint.
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:
164
207
165
-
You can visit `https://example.com/xrpc/_health` in your browser. You should see a JSON response with a version, like:
208
+
Visit `https://your-domain.net/xrpc/_health` in your browser. You should see a JSON response with a version, like:
166
209
167
210
```
168
211
{"version":"0.2.2-beta.2"}
···
174
217
wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0"
175
218
```
176
219
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.
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.
178
221
179
222
### Creating an account using pdsadmin
180
223
181
-
Using ssh on your server, use `pdsadmin` to create an account if you haven't already.
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:
182
225
183
226
```bash
184
227
sudo pdsadmin account create
···
186
229
187
230
### Creating an account using an invite code
188
231
189
-
Using ssh on your server, use `pdsadmin` to create an invite code.
232
+
If needed, use `pdsadmin` to create an invite code:
190
233
191
234
```bash
192
235
sudo pdsadmin create-invite-code
···
210
253
211
254
To be able to verify users' email addresses and send other emails, you need to set up an SMTP server.
212
255
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.
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.
214
257
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):
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):
216
259
217
260
```
218
261
PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:465/
···
265
308
266
309
### Updating your PDS
267
310
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.
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.
269
312
270
313
```bash
271
314
sudo pdsadmin update
+4
-1
installer.sh
+4
-1
installer.sh
···
105
105
elif [[ "${DISTRIB_CODENAME}" == "bookworm" ]]; then
106
106
SUPPORTED_OS="true"
107
107
echo "* Detected supported distribution Debian 12"
108
+
elif [[ "${DISTRIB_CODENAME}" == "trixie" ]]; then
109
+
SUPPORTED_OS="true"
110
+
echo "* Detected supported distribution Debian 13"
108
111
fi
109
112
fi
110
113
111
114
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..."
115
+
echo "Sorry, only Ubuntu 20.04, 22.04, 24.04, and Debian 11, 12, and 13 are supported by this installer. Exiting..."
113
116
exit 1
114
117
fi
115
118