vicwalker.dev.br
+186
ACCOUNT_MIGRATION.md
+186
ACCOUNT_MIGRATION.md
···
1
+
# Account Migration
2
+
3
+
### ⚠️ Warning ⚠️ ️
4
+
Account migration is a potentially destructive operation. Part of the operation involves signing away your old PDS's ability to make updates to your DID. If something goes wrong, you could be permanently locked out of your account, and Bluesky will not be able to help you recover it.
5
+
6
+
Therefore, we do not recommend migrating your primary account yet. And we specifically recommend _against_ migrating your main account if you do not understand how PLC operations work.
7
+
8
+
As well, the Bluesky PDS is not currently accepting incoming migrations (it will in the future). Therefore this is currently a one-way street. If you migrate off of `bsky.social`, _you will not be able to return_. However, you will be able to migrate between other PDSs.
9
+
10
+
...
11
+
12
+
13
+
14
+
Account Migration occurs in 4 main steps:
15
+
- Creating an account on the new PDS
16
+
- Migrating data from the old PDS to the new PDS
17
+
- Updating identity to point to the new PDS
18
+
- Finalizing the migration
19
+
20
+
21
+
### Creating an Account
22
+
23
+
In order to create an account, you first need to prove to the new PDS that you're in control of the DID that you're attempting to register as.
24
+
25
+
To do so, you need a JWT signed with the signing key associated with your DID. You can obtain this through calling `com.atproto.server.getServiceAuth` from your old PDS. If you're old PDS is not willing to provide the authentication token, you will need to update your DID document to point to a signing key that you possess in order to mint an authentication token yourself.
26
+
27
+
With this JWT set as a Bearer token, you can then create an account on the new PDS by calling `com.atproto.server.createAccount`. You'll need to fulfill any challenges that the new PDS requires - such as an invite code.
28
+
29
+
After creating an account, you'll have a signing key on the new PDS and an empty repository. You're account will be in a "deactivated" state such that it is not usable yet.
30
+
31
+
### Migrating data
32
+
33
+
Now that you have an account on the new PDS, you can start migrating data into it. After creating your account, you will have received an access token for the new PDS and it will be required for all incoming data.
34
+
35
+
First, you can grab your entire repository in the from of a [CAR file](https://ipld.io/specs/transport/car/carv1/) by calling `com.atproto.sync.getRepo`. You can then upload those exact bytes to your new PDS through `com.atproto.repo.importRepo`. The new PDS will parse the CAR file, index all blocks and records, and sign a new commit for the repository.
36
+
37
+
Next, you'll need to upload all relevant blobs. These can be discovered by calling `com.atproto.sync.listBlobs` on your old PDS. For each blob, you'll need to download the contents through `com.atproto.sync.getBlob` and upload them to your new PDS through `com.atproto.repo.uploadBlob`.
38
+
39
+
Finally, you'll need to migrate private state. Currently the only private state held on your PDS is your preferences. You can migrate this by calling `app.bsky.actor.getPreferences` on your old PDS, and submitting the results to `app.bsky.actor.putPreferences` on your new PDS.
40
+
41
+
At any point during this process, you can check the status of your new account by calling `com.atproto.server.checkAccountStatus` which will inform you of your repo state, how many records are indexed, how many private state values are stored, how many blobs it is expecting (based on parsing records), and how many blobs have been uploaded. If you find you are missing blobs and are not sure which, you may use `com.atproto.repo.listMissingBlobs` on your new PDS to find them.
42
+
43
+
### Updating identity
44
+
45
+
After your data has been migrated to your new PDS, you'll need to update your DID to point to the correct credentials - handle, pds endpoint, signing key, and (if using a did:plc) the new PDS's rotation key.
46
+
47
+
You can fetch your new PDS's recommendations for these by calling `com.atproto.identity.getRecommendedDidCredentials`. If using a did:plc, we recommend taking this chance to generate a new rotation key and adding it to the list of recommended rotation keys that comes from your new PDS.
48
+
49
+
If using a did:plc (as most accounts are), you can then request a signed PLC operation from your old PDS by passing the credentials through to `com.atproto.identity.signPlcOperation`. However, since this is a sensitive and possibly destructive operation, you'll need to fulfill an email challenge. To do so, simply call `com.atproto.identity.requestPlcOperationSignature` and send the provided token along with your request for a signed operation.
50
+
51
+
The operation you receive has the capability to update your PLC identity. Of course, you may submit it yourself to `https://plc.directory`. However, we strongly encourage you to submit it through your new PDS at `com.atproto.identity.submitPlcOperation`. Your new PDS will check the operation to ensure that it does not get your account into a bad state. We also encourage you to check the operation yourself.
52
+
53
+
If you are using a did:web or if your old PDS is not cooperating, you will need to take care of updating your DID yourself, either by updating the `.well-known` endpoint for your did:web or by signing a PLC operation with a rotation key that you possess.
54
+
55
+
### Finalizing the migration
56
+
57
+
After your identity is updated, you're nearly ready to go!
58
+
59
+
We recommend doing a final check of `com.atproto.server.checkAccountStatus` to ensure that everything looks in order.
60
+
61
+
After doing so, call `com.atproto.server.activateAccount` on your new PDS. It will ensure that your DID is set up correctly, activate your account, and send out events on its firehose noting that you updated your identity and published a new commit.
62
+
63
+
As a clean up step, you can deactivate or delete your account on your old PDS by calling `com.atproto.server.deleteAccount` or `com.atproto.server.deactivateAccount`. If doing the latter, you may provide an optional `deleteAfter` param that suggests to the server that it should hold onto your deactivated account until at least that date.
64
+
65
+
### After migration
66
+
67
+
After migrating, you should be good to start using the app as normal! You'll need to log out and log back in through your new PDS so that the client is talking to the correct service. It's possible that some services (such as feed generators) will have a stale DID cache and may not be able to accurately verify your auth tokens immediately. However, we've found that most services handle this gracefully, and those that don't should sort themselves out pretty quickly.
68
+
69
+
70
+
## Example Code
71
+
72
+
The below code gives an example of how this account migration flow may function. Please note that it is for documentation purposes only and can not be run exactly as is as there is an out-of-band step where you need to get a confirmation token from your email.
73
+
74
+
It does also not handle some of the more advanced steps such as verifying a full import, looking for missing blobs, adding your own recovery key, or validating the PLC operation itself.
75
+
76
+
```ts
77
+
import AtpAgent from '@atproto/api'
78
+
79
+
const OLD_PDS_URL = 'https://bsky.social'
80
+
const NEW_PDS_URL = 'https://example.com'
81
+
const CURRENT_HANDLE = 'to-migrate.bsky.social'
82
+
const CURRENT_PASSWORD = 'password'
83
+
const NEW_HANDLE = 'migrated.example.com'
84
+
const NEW_ACCOUNT_EMAIL = 'migrated@example.com'
85
+
const NEW_ACCOUNT_PASSWORD = 'password'
86
+
const NEW_PDS_INVITE_CODE = 'example-com-12345-abcde'
87
+
88
+
const migrateAccount = async () => {
89
+
const oldAgent = new AtpAgent({ service: OLD_PDS_URL })
90
+
const newAgent = new AtpAgent({ service: NEW_PDS_URL })
91
+
92
+
await oldAgent.login({
93
+
identifier: CURRENT_HANDLE,
94
+
password: CURRENT_PASSWORD,
95
+
})
96
+
97
+
const accountDid = oldAgent.session?.did
98
+
if (!accountDid) {
99
+
throw new Error('Could not get DID for old account')
100
+
}
101
+
102
+
// Create account
103
+
// ------------------
104
+
105
+
const describeRes = await newAgent.api.com.atproto.server.describeServer()
106
+
const newServerDid = describeRes.data.did
107
+
108
+
const serviceJwtRes = await oldAgent.com.atproto.server.getServiceAuth({
109
+
aud: newServerDid,
110
+
})
111
+
const serviceJwt = serviceJwtRes.data.token
112
+
113
+
await newAgent.api.com.atproto.server.createAccount(
114
+
{
115
+
handle: NEW_HANDLE,
116
+
email: NEW_ACCOUNT_EMAIL,
117
+
password: NEW_ACCOUNT_PASSWORD,
118
+
did: accountDid,
119
+
inviteCode: NEW_PDS_INVITE_CODE,
120
+
},
121
+
{
122
+
headers: { authorization: `Bearer ${serviceJwt}` },
123
+
encoding: 'application/json',
124
+
},
125
+
)
126
+
await newAgent.login({
127
+
identifier: NEW_HANDLE,
128
+
password: NEW_ACCOUNT_PASSWORD,
129
+
})
130
+
131
+
// Migrate Data
132
+
// ------------------
133
+
134
+
const repoRes = await oldAgent.com.atproto.sync.getRepo({ did: accountDid })
135
+
await newAgent.com.atproto.repo.importRepo(repoRes.data, {
136
+
encoding: 'application/vnd.ipld.car',
137
+
})
138
+
139
+
let blobCursor: string | undefined = undefined
140
+
do {
141
+
const listedBlobs = await oldAgent.com.atproto.sync.listBlobs({
142
+
did: accountDid,
143
+
cursor: blobCursor,
144
+
})
145
+
for (const cid of listedBlobs.data.cids) {
146
+
const blobRes = await oldAgent.com.atproto.sync.getBlob({
147
+
did: accountDid,
148
+
cid,
149
+
})
150
+
await newAgent.com.atproto.repo.uploadBlob(blobRes.data, {
151
+
encoding: blobRes.headers['content-type'],
152
+
})
153
+
}
154
+
blobCursor = listedBlobs.data.cursor
155
+
} while (blobCursor)
156
+
157
+
const prefs = await oldAgent.api.app.bsky.actor.getPreferences()
158
+
await newAgent.api.app.bsky.actor.putPreferences(prefs.data)
159
+
160
+
// Migrate Identity
161
+
// ------------------
162
+
163
+
await oldAgent.com.atproto.identity.requestPlcOperationSignature()
164
+
165
+
const getDidCredentials =
166
+
await newAgent.com.atproto.identity.getRecommendedDidCredentials()
167
+
168
+
// @NOTE, this token will need to come from the email from the previous step
169
+
const TOKEN = ''
170
+
171
+
const plcOp = await oldAgent.com.atproto.identity.signPlcOperation({
172
+
token: TOKEN,
173
+
...getDidCredentials.data,
174
+
})
175
+
176
+
await newAgent.com.atproto.identity.submitPlcOperation({
177
+
operation: plcOp.data.operation,
178
+
})
179
+
180
+
// Finalize Migration
181
+
// ------------------
182
+
183
+
await newAgent.com.atproto.server.activateAccount()
184
+
await oldAgent.com.atproto.server.deactivateAccount({})
185
+
}
186
+
```
+279
-60
README.md
+279
-60
README.md
···
4
4
5
5
## Table of Contents
6
6
7
-
<!-- markdown-toc -i README.md -->
8
-
9
-
<!-- toc -->
10
-
11
-
- [FAQ](#faq)
7
+
* [FAQ](#faq)
12
8
* [What is Bluesky?](#what-is-bluesky)
13
9
* [What is AT Protocol?](#what-is-at-protocol)
10
+
* [How can developers get invite codes?](#how-can-developers-get-invite-codes)
14
11
* [Where is the code?](#where-is-the-code)
15
12
* [What is the current status of federation?](#what-is-the-current-status-of-federation)
16
13
* [What should I know about running a PDS in the developer sandbox?](#what-should-i-know-about-running-a-pds-in-the-developer-sandbox)
17
-
- [Self-hosting PDS](#self-hosting-pds)
18
-
* [Preparation for self-hosting PDS](#preparation-for-self-hosting-pds)
14
+
* [Self\-hosting PDS](#self-hosting-pds)
15
+
* [Preparation for self\-hosting PDS](#preparation-for-self-hosting-pds)
19
16
* [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https)
20
17
* [Configure DNS for your domain](#configure-dns-for-your-domain)
21
18
* [Check that DNS is working as expected](#check-that-dns-is-working-as-expected)
22
-
* [Installer on Ubuntu 20.04/22.04 and Debian 11/12](#installer-on-ubuntu-20042204-and-debian-1112)
23
-
* [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible)
24
-
* [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin)
25
-
* [Creating an account using an invite code](#creating-an-account-using-an-invite-code)
26
-
* [Using the Bluesky app with your PDS](#using-the-bluesky-app-with-your-pds)
27
-
* [Updating your PDS](#updating-your-pds)
19
+
* [Automatic install on Ubuntu 20\.04/22\.04 or Debian 11/12](#automatic-install-on-ubuntu-20042204-or-debian-1112)
20
+
* [Installing manually on Ubuntu 22\.04](#installing-manually-on-ubuntu-2204)
21
+
* [Open ports on your Linux firewall](#open-ports-on-your-linux-firewall)
22
+
* [Install Docker](#install-docker)
23
+
* [Uninstall old versions](#uninstall-old-versions)
24
+
* [Set up the repository](#set-up-the-repository)
25
+
* [Install Docker Engine](#install-docker-engine)
26
+
* [Verify Docker Engine installation](#verify-docker-engine-installation)
27
+
* [Set up the PDS directory](#set-up-the-pds-directory)
28
+
* [Create the Caddyfile](#create-the-caddyfile)
29
+
* [Create the PDS env configuration file](#create-the-pds-env-configuration-file)
30
+
* [Start the PDS containers](#start-the-pds-containers)
31
+
* [Download the Docker compose file](#download-the-docker-compose-file)
32
+
* [Create the systemd service](#create-the-systemd-service)
33
+
* [Start the service](#start-the-service)
34
+
* [Verify your PDS is online](#verify-your-pds-is-online)
35
+
* [Obtain your PDS admin password](#obtain-your-pds-admin-password)
36
+
* [Generate an invite code for your PDS](#generate-an-invite-code-for-your-pds)
37
+
* [Connecting to your server](#connecting-to-your-server)
38
+
* [Manually updating your PDS](#manually-updating-your-pds)
39
+
* [PDS environment variables](#pds-environment-variables)
28
40
29
-
<!-- tocstop -->
30
41
31
42
## FAQ
32
43
···
34
45
35
46
Bluesky is a social media application built on AT Protocol.
36
47
37
-
Please visit the [Bluesky website](https://bsky.social/) for more information.
48
+
Please visit the [Bluesky website](https://bsky.app/) for more information.
38
49
39
50
### What is AT Protocol?
40
51
···
42
53
43
54
Please visit the [AT Protocol docs](https://atproto.com/guides/overview) for additional information.
44
55
56
+
### How can developers get invite codes?
57
+
58
+
There is no invite required to join the sandbox network. Simply set up your own PDS and generate your own invite codes to create accounts. If you desire an account on the production network (on the official Bluesky PDS) please check out the [Bluesky Developer Waitlist](https://docs.google.com/forms/d/e/1FAIpQLSfCuguykw3HaPxIZMJQKRu8_-vsRew90NALVTDOjCSPDmsGNg/viewform) which prioritizes access for developers wanting to build software on atproto.
59
+
45
60
### Where is the code?
46
61
47
-
* [TypeScript code](https://github.com/bluesky-social/atproto)
48
-
* [Go code](https://github.com/bluesky-social/indigo)
62
+
* [Canonical TypeScript code](https://github.com/bluesky-social/atproto)
63
+
* [Experimental Go code](https://github.com/bluesky-social/indigo)
49
64
50
65
### What is the current status of federation?
51
66
52
-
As of Feb, 2024, the AT Protocol data service (PDS) is now open to federation for self-hosters!
53
-
54
-
✅ Federated domain handles (e.g. `@nytimes.com`)
55
-
56
-
✅ Federated feed generators (custom algorithms)
57
-
58
-
✅ Federated relays (event firehose)
59
-
60
-
✅ Federated app views (API service)
61
-
62
-
✅ Federated data for self-hosters (PDS hosting)
63
-
64
-
🟩 Federated moderation (labeling) (coming soon)
65
-
66
-
🟩 Federated data for large service providers (coming soon)
67
+
We do not currently support PDS federation on the production network but it is now possible to federate in the developer sandbox.
67
68
68
69
### What should I know about running a PDS in the developer sandbox?
69
-
70
-
Developers may now run self-hosted PDS hosts on the production network!
71
-
72
-
Though it is still recommended to run experiments in the developer sandbox network.
73
70
74
71
Read the [SANDBOX.md](https://github.com/bluesky-social/pds/blob/main/SANDBOX.md) for an overview of the sandbox network.
75
72
···
137
134
138
135
These should all return your server's public IP.
139
136
140
-
### Installer on Ubuntu 20.04/22.04 and Debian 11/12
137
+
### Automatic install on Ubuntu 20.04/22.04 or Debian 11/12
141
138
142
-
On your server via ssh, download the installer script using wget:
139
+
On your server via ssh, run the installer script:
143
140
144
141
```bash
145
142
wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
146
143
```
147
144
148
-
or download it using curl:
145
+
```bash
146
+
sudo bash installer.sh
147
+
```
148
+
149
+
### Installing manually on Ubuntu 22.04
150
+
151
+
#### Open ports on your Linux firewall
152
+
153
+
If your server is running a Linux firewall managed with `ufw`, you will need to open these ports:
154
+
155
+
```bash
156
+
$ sudo ufw allow 80/tcp
157
+
$ sudo ufw allow 443/tcp
158
+
```
159
+
160
+
#### Install Docker
161
+
162
+
On your server, install Docker CE (Community Edition), using the the following instructions. For other operating systems you may reference the [official Docker install guides](https://docs.docker.com/engine/install/).
163
+
164
+
**Note:** All of the following commands should be run on your server via ssh.
165
+
166
+
##### Uninstall old versions
167
+
168
+
```bash
169
+
sudo apt-get remove docker docker-engine docker.io containerd runc
170
+
```
171
+
172
+
##### Set up the repository
173
+
174
+
```bash
175
+
sudo apt-get update
176
+
sudo apt-get install \
177
+
ca-certificates \
178
+
curl \
179
+
gnupg
180
+
```
181
+
182
+
```bash
183
+
sudo install -m 0755 -d /etc/apt/keyrings
184
+
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
185
+
sudo chmod a+r /etc/apt/keyrings/docker.gpg
186
+
```
187
+
188
+
```bash
189
+
echo \
190
+
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
191
+
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
192
+
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
193
+
```
194
+
195
+
##### Install Docker Engine
196
+
197
+
```bash
198
+
sudo apt-get update
199
+
```
200
+
201
+
```bash
202
+
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
203
+
```
204
+
205
+
##### Verify Docker Engine installation
206
+
207
+
```bash
208
+
sudo docker run hello-world
209
+
```
210
+
211
+
#### Set up the PDS directory
212
+
213
+
```bash
214
+
sudo mkdir /pds
215
+
sudo mkdir --parents /pds/caddy/data
216
+
sudo mkdir --parents /pds/caddy/etc/caddy
217
+
```
218
+
219
+
#### Create the Caddyfile
220
+
221
+
Be sure to replace `example.com` with your own domain.
222
+
223
+
```bash
224
+
cat <<CADDYFILE | sudo tee /pds/caddy/etc/caddy/Caddyfile
225
+
{
226
+
email you@example.com
227
+
}
228
+
229
+
*.example.com, example.com {
230
+
tls {
231
+
on_demand
232
+
}
233
+
reverse_proxy http://localhost:3000
234
+
}
235
+
CADDYFILE
236
+
```
237
+
238
+
#### Create the PDS env configuration file
239
+
240
+
You should fill in the first 5 values, but leave the rest untouched unless you have good reason to change it.
241
+
242
+
See the PDS environment variables section at the end of this README for explanations of each value
243
+
244
+
Your PDS will need two secp256k1 private keys provided as hex strings. You can securely generate these keys using `openssl` with the following command:
245
+
246
+
**Note:**
247
+
* Replace `example.com` with your domain name.
248
+
249
+
```bash
250
+
PDS_HOSTNAME="example.com"
251
+
PDS_JWT_SECRET="$(openssl rand --hex 16)"
252
+
PDS_ADMIN_PASSWORD="$(openssl rand --hex 16)"
253
+
PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX="$(openssl ecparam --name secp256k1 --genkey --noout --outform DER | tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32)"
254
+
PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX="$(openssl ecparam --name secp256k1 --genkey --noout --outform DER | tail --bytes=+8 | head --bytes=32 | xxd --plain --cols 32)"
255
+
256
+
cat <<PDS_CONFIG | sudo tee /pds/pds.env
257
+
PDS_HOSTNAME=${PDS_HOSTNAME}
258
+
PDS_JWT_SECRET=${PDS_JWT_SECRET}
259
+
PDS_ADMIN_PASSWORD=${PDS_ADMIN_PASSWORD}
260
+
PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX=${PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX}
261
+
PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX=${PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX}
262
+
PDS_DB_SQLITE_LOCATION=/pds/pds.sqlite
263
+
PDS_BLOBSTORE_DISK_LOCATION=/pds/blocks
264
+
PDS_DID_PLC_URL=https://plc.bsky-sandbox.dev
265
+
PDS_BSKY_APP_VIEW_URL=https://api.bsky-sandbox.dev
266
+
PDS_BSKY_APP_VIEW_DID=did:web:api.bsky-sandbox.dev
267
+
PDS_CRAWLERS=https://bgs.bsky-sandbox.dev
268
+
PDS_CONFIG
269
+
```
270
+
271
+
#### Start the PDS containers
272
+
273
+
##### Download the Docker compose file
274
+
275
+
Download the `compose.yaml` to run your PDS, which includes the following containers:
276
+
277
+
* `pds` Node PDS server running on http://localhost:3000
278
+
* `caddy` HTTP reverse proxy handling TLS and proxying requests to the PDS server
279
+
* `watchtower` Daemon responsible for auto-updating containers to keep the server secure and federating
280
+
281
+
```bash
282
+
curl https://raw.githubusercontent.com/bluesky-social/pds/main/compose.yaml | sudo tee /pds/compose.yaml
283
+
```
284
+
285
+
##### Create the systemd service
149
286
150
287
```bash
151
-
curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh
288
+
cat <<SYSTEMD_UNIT_FILE >/etc/systemd/system/pds.service
289
+
[Unit]
290
+
Description=Bluesky PDS Service
291
+
Documentation=https://github.com/bluesky-social/pds
292
+
Requires=docker.service
293
+
After=docker.service
294
+
295
+
[Service]
296
+
Type=oneshot
297
+
RemainAfterExit=yes
298
+
WorkingDirectory=/pds
299
+
ExecStart=/usr/bin/docker compose --file /pds/compose.yaml up --detach
300
+
ExecStop=/usr/bin/docker compose --file /pds/compose.yaml down
301
+
302
+
[Install]
303
+
WantedBy=default.target
304
+
SYSTEMD_UNIT_FILE
152
305
```
153
306
154
-
And then run the installer using bash:
307
+
##### Start the service
155
308
309
+
**Reload the systemd daemon to create the new service:**
156
310
```bash
157
-
sudo bash installer.sh
311
+
sudo systemctl daemon-reload
312
+
```
313
+
314
+
**Enable the systemd service:**
315
+
```bash
316
+
sudo systemctl enable pds
158
317
```
159
318
160
-
### Verifying that your PDS is online and accessible
319
+
**Start the pds systemd service:**
320
+
```bash
321
+
sudo systemctl start pds
322
+
```
161
323
162
-
You can check if your server is online and healthy by requesting the healthcheck endpoint.
324
+
**Ensure that containers are running**
163
325
164
-
You can visit `https://example.com/xrpc/_health` in your browser. You should see a JSON response with a version.
326
+
There should be a caddy, pds, and watchtower container running.
165
327
166
-
For example:
328
+
```bash
329
+
sudo systemctl status pds
330
+
```
167
331
332
+
```bash
333
+
sudo docker ps
168
334
```
335
+
336
+
### Verify your PDS is online
337
+
338
+
You can check if your server is online and healthy by requesting the healthcheck endpoint.
339
+
340
+
```bash
341
+
curl https://example.com/xrpc/_health
169
342
{"version":"0.2.2-beta.2"}
170
343
```
171
344
172
-
### Creating an account using pdsadmin
345
+
### Obtain your PDS admin password
346
+
347
+
Your PDS admin password should be in your `pds.env` file if you used the installer script.
173
348
174
-
Using ssh on your server, use `pdsadmin` to create an account if you haven't already.
349
+
**For example:**
175
350
176
351
```bash
177
-
sudo pdsadmin account create
352
+
$ source /pds/pds.env
353
+
$ echo $PDS_ADMIN_PASSWORD
354
+
a7b5970b6a5077bb41fc68a26d30adda
178
355
```
356
+
### Generate an invite code for your PDS
179
357
180
-
### Creating an account using an invite code
358
+
By default, your PDS will require an invite code to create an account.
181
359
182
-
Using ssh on your server, use `pdsadmin` to create an invite code.
360
+
You can generate a new invite code with the following command:
183
361
184
362
```bash
185
-
sudo pdsadmin create-invite-code
363
+
PDS_HOSTNAME="example.com"
364
+
PDS_ADMIN_PASSWORD="<YOUR PDS ADMIN PASSWORD>"
365
+
366
+
curl --silent \
367
+
--show-error \
368
+
--request POST \
369
+
--user "admin:${PDS_ADMIN_PASSWORD}" \
370
+
--header "Content-Type: application/json" \
371
+
--data '{"useCount": 1}' \
372
+
https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createInviteCode
186
373
```
187
374
188
-
When creating an account using the app, enter this invite code.
375
+
**Note:** the `useCount` field specifies how many times an invite code can be used
189
376
190
-
### Using the Bluesky app with your PDS
377
+
### Connecting to your server
191
378
192
-
You can use the Bluesky app to connect to your PDS.
379
+
You can use the Bluesky app to connect to your server to create an account.
193
380
194
381
1. Get the Bluesky app
195
-
* [Bluesky for Web](https://bsky.app/)
382
+
* [Bluesky for Web (sandbox)](https://app.bsky-sandbox.dev/)
196
383
* [Bluesky for iPhone](https://apps.apple.com/us/app/bluesky-social/id6444370199)
197
384
* [Bluesky for Android](https://play.google.com/store/apps/details?id=xyz.blueskyweb.app)
198
385
1. Enter the URL of your PDS (e.g. `https://example.com/`)
386
+
1. Create an account using the generated invite code
387
+
1. Create a post
388
+
389
+
_Note: because we use on-the-fly TLS certs, 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._
199
390
200
-
_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._
391
+
Checkout [SANDBOX.md](./SANDBOX.md) for an overview of participating in the sandbox network.
392
+
393
+
### Manually updating your PDS
201
394
202
-
### Updating your PDS
395
+
If you use use Docker `compose.yaml` file in this repo, your PDS will automatically update nightly. To manually update to the latest version use the following commands.
203
396
204
-
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.
397
+
**Pull the latest PDS container image:**
398
+
```bash
399
+
sudo docker pull ghcr.io/bluesky-social/pds:latest
400
+
```
205
401
402
+
**Restart PDS with the new container image:**
206
403
```bash
207
-
sudo pdsadmin update
404
+
sudo systemctl restart pds
208
405
```
406
+
407
+
## PDS environment variables
408
+
409
+
You will need to customize various settings configured through the PDS environment variables. See the below table to find the variables you'll need to set.
410
+
411
+
| Environment Variable | Value | Should update? | Notes |
412
+
| ----------------------------------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------- |
413
+
| PDS_HOSTNAME | example.com | ✅ | Public domain you intend to deploy your service at |
414
+
| PDS_JWT_SECRET | jwt-secret | ✅ | Use a secure high-entropy string that is 32 characters in length |
415
+
| PDS_ADMIN_PASSWORD | admin-pass | ✅ | Use a secure high-entropy string that is 32 characters in length |
416
+
| PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX | 3ee68... | ✅ | See above Generate Keys section - once set, do not change |
417
+
| PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX | e049f... | ✅ | See above Generate Keys section - once set, do not change |
418
+
| PDS_DB_SQLITE_LOCATION | /pds/pds.sqlite | ❌ | Or use `PDS_DB_POSTGRES_URL` depending on which database you intend to use |
419
+
| PDS_BLOBSTORE_DISK_LOCATION | /pds/blocks | ❌ | Only update if you update the mounted volume for your docker image as well |
420
+
| PDS_DID_PLC_URL | https://plc.bsky-sandbox.dev | ❌ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
421
+
| PDS_BSKY_APP_VIEW_URL | https://api.bsky-sandbox.dev | ❌ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
422
+
| PDS_BSKY_APP_VIEW_DID | did:web:api.bsky-sandbox.dev | ❌ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
423
+
| PDS_CRAWLERS | https://bgs.bsky-sandbox.dev | ❌ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
424
+
425
+
There are additional environment variables that can be tweaked depending on how you're running your service. For instance, storing blobs in AWS S3, keys in AWS KMS, or setting up an email service.
426
+
427
+
Feel free to explore those [Here](https://github.com/bluesky-social/atproto/blob/simplify-pds/packages/pds/src/config/env.ts). However, we will not be providing support for more advanced configurations.
+3
-29
SANDBOX.md
+3
-29
SANDBOX.md
···
10
10
11
11
Given that this is a testing environment, we will be defederating from any instances that do not abide by these guidelines, or that cause unnecessary trouble, and will not be providing specific justifications for these decisions.
12
12
13
-
<!-- markdown-toc -i SANDBOX.md -->
14
-
15
-
<!-- toc -->
16
-
17
-
- [Guidelines that must be followed](#guidelines-that-must-be-followed)
18
-
* [Post responsibly](#post-responsibly)
19
-
* [Keep the emphasis on testing](#keep-the-emphasis-on-testing)
20
-
* [Do limit account creation](#do-limit-account-creation)
21
-
* [Don’t expect persistence or uptime](#dont-expect-persistence-or-uptime)
22
-
* [Don't advertise your service as being "Bluesky"](#dont-advertise-your-service-as-being-bluesky)
23
-
* [Do not mirror sandbox did:plcs to production](#do-not-mirror-sandbox-didplcs-to-production)
24
-
* [Status and Wipes](#status-and-wipes)
25
-
+ [🐉 Beware of dragons!](#%F0%9F%90%89-beware-of-dragons)
26
-
+ [Routine wipes](#routine-wipes)
27
-
- [Getting started](#getting-started)
28
-
* [Auto-updates](#auto-updates)
29
-
* [Odds & Ends & Warnings & Reminders](#odds--ends--warnings--reminders)
30
-
- [Learn more about atproto federation](#learn-more-about-atproto-federation)
31
-
* [Network Services](#network-services)
32
-
+ [PLC](#plc)
33
-
+ [BGS](#bgs)
34
-
+ [Bluesky App View](#bluesky-app-view)
35
-
- [The PDS](#the-pds)
36
-
37
-
<!-- tocstop -->
38
-
39
13
# Guidelines that must be followed
40
14
41
15
Using the sandbox environment means you agree to adhere to our Guidelines. Please read the following carefully:
···
44
18
45
19
The sandbox environment is intended to test infrastructure, but user content may be created as part of this testing process. Content generation can be automated or manual.
46
20
47
-
Do not post content that requires active moderation or violates the [Bluesky Community Guidelines](https://bsky.social/about/support/community-guidelines).
21
+
Do not post content that requires active moderation or violates the [Bluesky Community Guidelines](https://blueskyweb.xyz/support/community-guidelines).
48
22
49
23
## Keep the emphasis on testing
50
24
···
119
93
120
94
# Learn more about atproto federation
121
95
122
-
Check out the [high-level view of federation](https://bsky.social/about/blog/5-5-2023-federation-architecture).
96
+
Check out the [high-level view of federation](https://blueskyweb.xyz/blog/5-5-2023-federation-architecture).
123
97
124
98
Dive deeper with the [atproto docs](https://atproto.com/docs).
125
99
···
165
139
166
140
We’re not actually running a Bluesky PDS in sandbox. You might see Bluesky team members' accounts in the sandbox environment, but those are self-hosted too.
167
141
168
-
The PDS that you’ll be running is much of the same code that is running on the Bluesky production PDS. Notably, all of the in-pds-appview code has been torn out. You can see the actual PDS code that you’re running on the [atproto/simplify-pds](https://github.com/bluesky-social/atproto/pull/1198) branch.
142
+
The PDS that you’ll be running is much of the same code that is running on the Bluesky production PDS. Notably, all of the in-pds-appview code has been torn out. You can see the actual PDS code that you’re running on the [atproto/simplify-pds](https://github.com/bluesky-social/atproto/pull/1198) branch.
assets/account-migration.png
assets/account-migration.png
This is a binary file and will not be displayed.