···11+# Account Migration
22+33+### โ ๏ธ Warning โ ๏ธ ๏ธ
44+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.
55+66+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.
77+88+Also, 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.
99+1010+
1111+1212+Account Migration occurs in 4 main steps:
1313+- Creating an account on the new PDS
1414+- Migrating data from the old PDS to the new PDS
1515+- Updating identity to point to the new PDS
1616+- Finalizing the migration
1717+1818+1919+### Creating an Account
2020+2121+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.
2222+2323+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 your 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.
2424+2525+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.
2626+2727+After creating an account, you'll have a signing key on the new PDS and an empty repository. Your account will be in a "deactivated" state such that it is not usable yet.
2828+2929+### Migrating data
3030+3131+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.
3232+3333+First, you can grab your entire repository in the form 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.
3434+3535+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`.
3636+3737+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.
3838+3939+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.
4040+4141+### Updating identity
4242+4343+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.
4444+4545+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.
4646+4747+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.
4848+4949+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.
5050+5151+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.
5252+5353+### Finalizing the migration
5454+5555+After your identity is updated, you're nearly ready to go!
5656+5757+We recommend doing a final check of `com.atproto.server.checkAccountStatus` to ensure that everything looks in order.
5858+5959+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.
6060+6161+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.
6262+6363+### After migration
6464+6565+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.
6666+6767+6868+## Example Code
6969+7070+The below Typescript 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.
7171+7272+It also does 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.
7373+7474+```ts
7575+import AtpAgent from '@atproto/api'
7676+import { Secp256k1Keypair } from '@atproto/crypto'
7777+import * as ui8 from 'uint8arrays'
7878+7979+const OLD_PDS_URL = 'https://bsky.social'
8080+const NEW_PDS_URL = 'https://example.com'
8181+const CURRENT_HANDLE = 'to-migrate.bsky.social'
8282+const CURRENT_PASSWORD = 'password'
8383+const NEW_HANDLE = 'migrated.example.com'
8484+const NEW_ACCOUNT_EMAIL = 'migrated@example.com'
8585+const NEW_ACCOUNT_PASSWORD = 'password'
8686+const NEW_PDS_INVITE_CODE = 'example-com-12345-abcde'
8787+8888+const migrateAccount = async () => {
8989+ const oldAgent = new AtpAgent({ service: OLD_PDS_URL })
9090+ const newAgent = new AtpAgent({ service: NEW_PDS_URL })
9191+9292+ await oldAgent.login({
9393+ identifier: CURRENT_HANDLE,
9494+ password: CURRENT_PASSWORD,
9595+ })
9696+9797+ const accountDid = oldAgent.session?.did
9898+ if (!accountDid) {
9999+ throw new Error('Could not get DID for old account')
100100+ }
101101+102102+ // Create account
103103+ // ------------------
104104+105105+ const describeRes = await newAgent.api.com.atproto.server.describeServer()
106106+ const newServerDid = describeRes.data.did
107107+108108+ const serviceJwtRes = await oldAgent.com.atproto.server.getServiceAuth({
109109+ aud: newServerDid,
110110+ lxm: 'com.atproto.server.createAccount',
111111+ })
112112+ const serviceJwt = serviceJwtRes.data.token
113113+114114+ await newAgent.api.com.atproto.server.createAccount(
115115+ {
116116+ handle: NEW_HANDLE,
117117+ email: NEW_ACCOUNT_EMAIL,
118118+ password: NEW_ACCOUNT_PASSWORD,
119119+ did: accountDid,
120120+ inviteCode: NEW_PDS_INVITE_CODE,
121121+ },
122122+ {
123123+ headers: { authorization: `Bearer ${serviceJwt}` },
124124+ encoding: 'application/json',
125125+ },
126126+ )
127127+ await newAgent.login({
128128+ identifier: NEW_HANDLE,
129129+ password: NEW_ACCOUNT_PASSWORD,
130130+ })
131131+132132+ // Migrate Data
133133+ // ------------------
134134+135135+ const repoRes = await oldAgent.com.atproto.sync.getRepo({ did: accountDid })
136136+ await newAgent.com.atproto.repo.importRepo(repoRes.data, {
137137+ encoding: 'application/vnd.ipld.car',
138138+ })
139139+140140+ let blobCursor: string | undefined = undefined
141141+ do {
142142+ const listedBlobs = await oldAgent.com.atproto.sync.listBlobs({
143143+ did: accountDid,
144144+ cursor: blobCursor,
145145+ })
146146+ for (const cid of listedBlobs.data.cids) {
147147+ const blobRes = await oldAgent.com.atproto.sync.getBlob({
148148+ did: accountDid,
149149+ cid,
150150+ })
151151+ await newAgent.com.atproto.repo.uploadBlob(blobRes.data, {
152152+ encoding: blobRes.headers['content-type'],
153153+ })
154154+ }
155155+ blobCursor = listedBlobs.data.cursor
156156+ } while (blobCursor)
157157+158158+ const prefs = await oldAgent.api.app.bsky.actor.getPreferences()
159159+ await newAgent.api.app.bsky.actor.putPreferences(prefs.data)
160160+161161+ // Migrate Identity
162162+ // ------------------
163163+164164+ const recoveryKey = await Secp256k1Keypair.create({ exportable: true })
165165+ const privateKeyBytes = await recoveryKey.export()
166166+ const privateKey = ui8.toString(privateKeyBytes, 'hex')
167167+168168+ await oldAgent.com.atproto.identity.requestPlcOperationSignature()
169169+170170+ const getDidCredentials =
171171+ await newAgent.com.atproto.identity.getRecommendedDidCredentials()
172172+ const rotationKeys = getDidCredentials.data.rotationKeys ?? []
173173+ if (!rotationKeys) {
174174+ throw new Error('No rotation key provided')
175175+ }
176176+ const credentials = {
177177+ ...getDidCredentials.data,
178178+ rotationKeys: [recoveryKey.did(), ...rotationKeys],
179179+ }
180180+181181+ // @NOTE, this token will need to come from the email from the previous step
182182+ const TOKEN = ''
183183+184184+ const plcOp = await oldAgent.com.atproto.identity.signPlcOperation({
185185+ token: TOKEN,
186186+ ...credentials,
187187+ })
188188+189189+ console.log(
190190+ `โ Your private recovery key is: ${privateKey}. Please store this in a secure location! โ`,
191191+ )
192192+193193+ await newAgent.com.atproto.identity.submitPlcOperation({
194194+ operation: plcOp.data.operation,
195195+ })
196196+197197+ // Finalize Migration
198198+ // ------------------
199199+200200+ await newAgent.com.atproto.server.activateAccount()
201201+ await oldAgent.com.atproto.server.deactivateAccount({})
202202+}
203203+204204+```
+9-4
Dockerfile
···11-FROM node:18-alpine as build
11+FROM node:20.11-alpine3.18 as build
22+33+RUN corepack enable
2435# Move files into the image and install
46WORKDIR /app
57COPY ./service ./
66-RUN yarn install --production --frozen-lockfile > /dev/null
88+RUN corepack prepare --activate
99+RUN pnpm install --production --frozen-lockfile > /dev/null
710811# Uses assets from build stage to reduce build size
99-FROM node:18-alpine
1212+FROM node:20.11-alpine3.18
10131114RUN apk add --update dumb-init
1215···1922EXPOSE 3000
2023ENV PDS_PORT=3000
2124ENV NODE_ENV=production
2525+# potential perf issues w/ io_uring on this version of node
2626+ENV UV_USE_IO_URING=0
22272328CMD ["node", "--enable-source-maps", "index.js"]
24292530LABEL org.opencontainers.image.source=https://github.com/bluesky-social/pds
2626-LABEL org.opencontainers.image.description="ATP Personal Data Server (PDS)"
3131+LABEL org.opencontainers.image.description="AT Protocol PDS"
2732LABEL org.opencontainers.image.licenses=MIT
+202
LICENSE-APACHE.txt
···11+22+ Apache License
33+ Version 2.0, January 2004
44+ http://www.apache.org/licenses/
55+66+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
77+88+ 1. Definitions.
99+1010+ "License" shall mean the terms and conditions for use, reproduction,
1111+ and distribution as defined by Sections 1 through 9 of this document.
1212+1313+ "Licensor" shall mean the copyright owner or entity authorized by
1414+ the copyright owner that is granting the License.
1515+1616+ "Legal Entity" shall mean the union of the acting entity and all
1717+ other entities that control, are controlled by, or are under common
1818+ control with that entity. For the purposes of this definition,
1919+ "control" means (i) the power, direct or indirect, to cause the
2020+ direction or management of such entity, whether by contract or
2121+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
2222+ outstanding shares, or (iii) beneficial ownership of such entity.
2323+2424+ "You" (or "Your") shall mean an individual or Legal Entity
2525+ exercising permissions granted by this License.
2626+2727+ "Source" form shall mean the preferred form for making modifications,
2828+ including but not limited to software source code, documentation
2929+ source, and configuration files.
3030+3131+ "Object" form shall mean any form resulting from mechanical
3232+ transformation or translation of a Source form, including but
3333+ not limited to compiled object code, generated documentation,
3434+ and conversions to other media types.
3535+3636+ "Work" shall mean the work of authorship, whether in Source or
3737+ Object form, made available under the License, as indicated by a
3838+ copyright notice that is included in or attached to the work
3939+ (an example is provided in the Appendix below).
4040+4141+ "Derivative Works" shall mean any work, whether in Source or Object
4242+ form, that is based on (or derived from) the Work and for which the
4343+ editorial revisions, annotations, elaborations, or other modifications
4444+ represent, as a whole, an original work of authorship. For the purposes
4545+ of this License, Derivative Works shall not include works that remain
4646+ separable from, or merely link (or bind by name) to the interfaces of,
4747+ the Work and Derivative Works thereof.
4848+4949+ "Contribution" shall mean any work of authorship, including
5050+ the original version of the Work and any modifications or additions
5151+ to that Work or Derivative Works thereof, that is intentionally
5252+ submitted to Licensor for inclusion in the Work by the copyright owner
5353+ or by an individual or Legal Entity authorized to submit on behalf of
5454+ the copyright owner. For the purposes of this definition, "submitted"
5555+ means any form of electronic, verbal, or written communication sent
5656+ to the Licensor or its representatives, including but not limited to
5757+ communication on electronic mailing lists, source code control systems,
5858+ and issue tracking systems that are managed by, or on behalf of, the
5959+ Licensor for the purpose of discussing and improving the Work, but
6060+ excluding communication that is conspicuously marked or otherwise
6161+ designated in writing by the copyright owner as "Not a Contribution."
6262+6363+ "Contributor" shall mean Licensor and any individual or Legal Entity
6464+ on behalf of whom a Contribution has been received by Licensor and
6565+ subsequently incorporated within the Work.
6666+6767+ 2. Grant of Copyright License. Subject to the terms and conditions of
6868+ this License, each Contributor hereby grants to You a perpetual,
6969+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
7070+ copyright license to reproduce, prepare Derivative Works of,
7171+ publicly display, publicly perform, sublicense, and distribute the
7272+ Work and such Derivative Works in Source or Object form.
7373+7474+ 3. Grant of Patent License. Subject to the terms and conditions of
7575+ this License, each Contributor hereby grants to You a perpetual,
7676+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
7777+ (except as stated in this section) patent license to make, have made,
7878+ use, offer to sell, sell, import, and otherwise transfer the Work,
7979+ where such license applies only to those patent claims licensable
8080+ by such Contributor that are necessarily infringed by their
8181+ Contribution(s) alone or by combination of their Contribution(s)
8282+ with the Work to which such Contribution(s) was submitted. If You
8383+ institute patent litigation against any entity (including a
8484+ cross-claim or counterclaim in a lawsuit) alleging that the Work
8585+ or a Contribution incorporated within the Work constitutes direct
8686+ or contributory patent infringement, then any patent licenses
8787+ granted to You under this License for that Work shall terminate
8888+ as of the date such litigation is filed.
8989+9090+ 4. Redistribution. You may reproduce and distribute copies of the
9191+ Work or Derivative Works thereof in any medium, with or without
9292+ modifications, and in Source or Object form, provided that You
9393+ meet the following conditions:
9494+9595+ (a) You must give any other recipients of the Work or
9696+ Derivative Works a copy of this License; and
9797+9898+ (b) You must cause any modified files to carry prominent notices
9999+ stating that You changed the files; and
100100+101101+ (c) You must retain, in the Source form of any Derivative Works
102102+ that You distribute, all copyright, patent, trademark, and
103103+ attribution notices from the Source form of the Work,
104104+ excluding those notices that do not pertain to any part of
105105+ the Derivative Works; and
106106+107107+ (d) If the Work includes a "NOTICE" text file as part of its
108108+ distribution, then any Derivative Works that You distribute must
109109+ include a readable copy of the attribution notices contained
110110+ within such NOTICE file, excluding those notices that do not
111111+ pertain to any part of the Derivative Works, in at least one
112112+ of the following places: within a NOTICE text file distributed
113113+ as part of the Derivative Works; within the Source form or
114114+ documentation, if provided along with the Derivative Works; or,
115115+ within a display generated by the Derivative Works, if and
116116+ wherever such third-party notices normally appear. The contents
117117+ of the NOTICE file are for informational purposes only and
118118+ do not modify the License. You may add Your own attribution
119119+ notices within Derivative Works that You distribute, alongside
120120+ or as an addendum to the NOTICE text from the Work, provided
121121+ that such additional attribution notices cannot be construed
122122+ as modifying the License.
123123+124124+ You may add Your own copyright statement to Your modifications and
125125+ may provide additional or different license terms and conditions
126126+ for use, reproduction, or distribution of Your modifications, or
127127+ for any such Derivative Works as a whole, provided Your use,
128128+ reproduction, and distribution of the Work otherwise complies with
129129+ the conditions stated in this License.
130130+131131+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132132+ any Contribution intentionally submitted for inclusion in the Work
133133+ by You to the Licensor shall be under the terms and conditions of
134134+ this License, without any additional terms or conditions.
135135+ Notwithstanding the above, nothing herein shall supersede or modify
136136+ the terms of any separate license agreement you may have executed
137137+ with Licensor regarding such Contributions.
138138+139139+ 6. Trademarks. This License does not grant permission to use the trade
140140+ names, trademarks, service marks, or product names of the Licensor,
141141+ except as required for reasonable and customary use in describing the
142142+ origin of the Work and reproducing the content of the NOTICE file.
143143+144144+ 7. Disclaimer of Warranty. Unless required by applicable law or
145145+ agreed to in writing, Licensor provides the Work (and each
146146+ Contributor provides its Contributions) on an "AS IS" BASIS,
147147+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148148+ implied, including, without limitation, any warranties or conditions
149149+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150150+ PARTICULAR PURPOSE. You are solely responsible for determining the
151151+ appropriateness of using or redistributing the Work and assume any
152152+ risks associated with Your exercise of permissions under this License.
153153+154154+ 8. Limitation of Liability. In no event and under no legal theory,
155155+ whether in tort (including negligence), contract, or otherwise,
156156+ unless required by applicable law (such as deliberate and grossly
157157+ negligent acts) or agreed to in writing, shall any Contributor be
158158+ liable to You for damages, including any direct, indirect, special,
159159+ incidental, or consequential damages of any character arising as a
160160+ result of this License or out of the use or inability to use the
161161+ Work (including but not limited to damages for loss of goodwill,
162162+ work stoppage, computer failure or malfunction, or any and all
163163+ other commercial damages or losses), even if such Contributor
164164+ has been advised of the possibility of such damages.
165165+166166+ 9. Accepting Warranty or Additional Liability. While redistributing
167167+ the Work or Derivative Works thereof, You may choose to offer,
168168+ and charge a fee for, acceptance of support, warranty, indemnity,
169169+ or other liability obligations and/or rights consistent with this
170170+ License. However, in accepting such obligations, You may act only
171171+ on Your own behalf and on Your sole responsibility, not on behalf
172172+ of any other Contributor, and only if You agree to indemnify,
173173+ defend, and hold each Contributor harmless for any liability
174174+ incurred by, or claims asserted against, such Contributor by reason
175175+ of your accepting any such warranty or additional liability.
176176+177177+ END OF TERMS AND CONDITIONS
178178+179179+ APPENDIX: How to apply the Apache License to your work.
180180+181181+ To apply the Apache License to your work, attach the following
182182+ boilerplate notice, with the fields enclosed by brackets "[]"
183183+ replaced with your own identifying information. (Don't include
184184+ the brackets!) The text should be enclosed in the appropriate
185185+ comment syntax for the file format. We also recommend that a
186186+ file or class name and description of purpose be included on the
187187+ same "printed page" as the copyright notice for easier
188188+ identification within third-party archives.
189189+190190+ Copyright [yyyy] [name of copyright owner]
191191+192192+ Licensed under the Apache License, Version 2.0 (the "License");
193193+ you may not use this file except in compliance with the License.
194194+ You may obtain a copy of the License at
195195+196196+ http://www.apache.org/licenses/LICENSE-2.0
197197+198198+ Unless required by applicable law or agreed to in writing, software
199199+ distributed under the License is distributed on an "AS IS" BASIS,
200200+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201201+ See the License for the specific language governing permissions and
202202+ limitations under the License.
+19
LICENSE-MIT.txt
···11+MIT License
22+33+Permission is hereby granted, free of charge, to any person obtaining a copy
44+of this software and associated documentation files (the "Software"), to deal
55+in the Software without restriction, including without limitation the rights
66+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
77+copies of the Software, and to permit persons to whom the Software is
88+furnished to do so, subject to the following conditions:
99+1010+The above copyright notice and this permission notice shall be included in all
1111+copies or substantial portions of the Software.
1212+1313+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1414+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1515+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1616+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1717+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
1818+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1919+SOFTWARE.
+7
LICENSE.txt
···11+Dual MIT/Apache-2.0 License
22+33+Copyright (c) 2022-2024 Bluesky PBC, and Contributors
44+55+Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
66+77+Downstream projects and end users may chose 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.
+98-260
README.md
···11# PDS
2233-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 self-hosting a Bluesky PDS.
33+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.
44+55+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!
4657## Table of Contents
6877-* [FAQ](#faq)
99+<!-- markdown-toc -i README.md -->
1010+1111+<!-- toc -->
1212+1313+- [FAQ](#faq)
814 * [What is Bluesky?](#what-is-bluesky)
915 * [What is AT Protocol?](#what-is-at-protocol)
1010- * [How can developers get invite codes?](#how-can-developers-get-invite-codes)
1116 * [Where is the code?](#where-is-the-code)
1217 * [What is the current status of federation?](#what-is-the-current-status-of-federation)
1313- * [What should I know about running a PDS in the developer sandbox?](#what-should-i-know-about-running-a-pds-in-the-developer-sandbox)
1414-* [Self\-hosting PDS](#self-hosting-pds)
1515- * [Preparation for self\-hosting PDS](#preparation-for-self-hosting-pds)
1818+- [Self-hosting PDS](#self-hosting-pds)
1919+ * [Preparation for self-hosting PDS](#preparation-for-self-hosting-pds)
1620 * [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https)
1721 * [Configure DNS for your domain](#configure-dns-for-your-domain)
1822 * [Check that DNS is working as expected](#check-that-dns-is-working-as-expected)
1919- * [Automatic install on Ubuntu 20\.04/22\.04 or Debian 11/12](#automatic-install-on-ubuntu-20042204-or-debian-1112)
2020- * [Installing manually on Ubuntu 22\.04](#installing-manually-on-ubuntu-2204)
2121- * [Open ports on your Linux firewall](#open-ports-on-your-linux-firewall)
2222- * [Install Docker](#install-docker)
2323- * [Uninstall old versions](#uninstall-old-versions)
2424- * [Set up the repository](#set-up-the-repository)
2525- * [Install Docker Engine](#install-docker-engine)
2626- * [Verify Docker Engine installation](#verify-docker-engine-installation)
2727- * [Set up the PDS directory](#set-up-the-pds-directory)
2828- * [Create the Caddyfile](#create-the-caddyfile)
2929- * [Create the PDS env configuration file](#create-the-pds-env-configuration-file)
3030- * [Start the PDS containers](#start-the-pds-containers)
3131- * [Download the Docker compose file](#download-the-docker-compose-file)
3232- * [Create the systemd service](#create-the-systemd-service)
3333- * [Start the service](#start-the-service)
3434- * [Verify your PDS is online](#verify-your-pds-is-online)
3535- * [Obtain your PDS admin password](#obtain-your-pds-admin-password)
3636- * [Generate an invite code for your PDS](#generate-an-invite-code-for-your-pds)
3737- * [Connecting to your server](#connecting-to-your-server)
3838- * [Manually updating your PDS](#manually-updating-your-pds)
3939-* [PDS environment variables](#pds-environment-variables)
2323+ * [Installer on Ubuntu 20.04/22.04 and Debian 11/12](#installer-on-ubuntu-20042204-and-debian-1112)
2424+ * [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible)
2525+ * [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin)
2626+ * [Creating an account using an invite code](#creating-an-account-using-an-invite-code)
2727+ * [Using the Bluesky app with your PDS](#using-the-bluesky-app-with-your-pds)
2828+ * [Setting up SMTP](#setting-up-smtp)
2929+ * [Updating your PDS](#updating-your-pds)
40303131+<!-- tocstop -->
41324233## FAQ
4334···45364637Bluesky is a social media application built on AT Protocol.
47384848-Please visit the [Bluesky website](https://bsky.app/) for more information.
3939+Please visit the [Bluesky website](https://bsky.social/) for more information.
49405041### What is AT Protocol?
5142···53445445Please visit the [AT Protocol docs](https://atproto.com/guides/overview) for additional information.
55465656-### How can developers get invite codes?
4747+### Where is the code?
57485858-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.
4949+* [TypeScript code](https://github.com/bluesky-social/atproto/tree/main/packages/pds)
5050+* [Go code](https://github.com/bluesky-social/indigo)
59516060-### Where is the code?
5252+### What is the current status of federation?
5353+5454+As of Spring 2024, the AT Protocol network is open to federation!
5555+5656+โ Federated domain handles (e.g. `@nytimes.com`)
61576262-* [Canonical TypeScript code](https://github.com/bluesky-social/atproto)
6363-* [Experimental Go code](https://github.com/bluesky-social/indigo)
5858+โ Federated feed generators (custom algorithms)
64596565-### What is the current status of federation?
6060+โ Federated relays (event firehose)
66616767-We do not currently support PDS federation on the production network but it is now possible to federate in the developer sandbox.
6262+โ Federated app views (API service)
68636969-### What should I know about running a PDS in the developer sandbox?
6464+โ Federated data (PDS hosting)
70657171-Read the [SANDBOX.md](https://github.com/bluesky-social/pds/blob/main/SANDBOX.md) for an overview of the sandbox network.
6666+โ Federated moderation (labeling)
72677368## Self-hosting PDS
7469···8984| | |
9085| ---------------- | ------------ |
9186| Operating System | Ubuntu 22.04 |
9292-| Memory (RAM) | 2+ GB |
9393-| CPU Cores | 2+ |
9494-| Storage | 40+ GB SSD |
8787+| Memory (RAM) | 1 GB |
8888+| CPU Cores | 1 |
8989+| Storage | 20 GB SSD |
9590| Architectures | amd64, arm64 |
9696-9191+| Number of users | 1-20 |
9292+9793**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/).
98949995### Open your cloud firewall for HTTP and HTTPS
···134130135131These should all return your server's public IP.
136132137137-### Automatic install on Ubuntu 20.04/22.04 or Debian 11/12
133133+### Installer on Ubuntu 20.04/22.04 and Debian 11/12
138134139139-On your server via ssh, run the installer script:
135135+On your server via ssh, download the installer script using wget:
140136141137```bash
142138wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
143139```
144140141141+or download it using curl:
142142+145143```bash
146146-sudo bash installer.sh
144144+curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh
147145```
148146149149-### Installing manually on Ubuntu 22.04
150150-151151-#### Open ports on your Linux firewall
152152-153153-If your server is running a Linux firewall managed with `ufw`, you will need to open these ports:
147147+And then run the installer using bash:
154148155149```bash
156156-$ sudo ufw allow 80/tcp
157157-$ sudo ufw allow 443/tcp
150150+sudo bash installer.sh
158151```
159152160160-#### Install Docker
153153+### Verifying that your PDS is online and accessible
161154162162-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/).
155155+> [!TIP]
156156+> 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.
163157164164-**Note:** All of the following commands should be run on your server via ssh.
158158+You can check if your server is online and healthy by requesting the healthcheck endpoint.
165159166166-##### Uninstall old versions
160160+You can visit `https://example.com/xrpc/_health` in your browser. You should see a JSON response with a version, like:
167161168168-```bash
169169-sudo apt-get remove docker docker-engine docker.io containerd runc
170162```
171171-172172-##### Set up the repository
173173-174174-```bash
175175-sudo apt-get update
176176-sudo apt-get install \
177177- ca-certificates \
178178- curl \
179179- gnupg
163163+{"version":"0.2.2-beta.2"}
180164```
181165182182-```bash
183183-sudo install -m 0755 -d /etc/apt/keyrings
184184-curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
185185-sudo chmod a+r /etc/apt/keyrings/docker.gpg
186186-```
166166+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:
187167188168```bash
189189-echo \
190190- "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
191191- "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
192192- sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
169169+wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0"
193170```
194171195195-##### Install Docker Engine
172172+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.
196173197197-```bash
198198-sudo apt-get update
199199-```
174174+### Creating an account using pdsadmin
200175201201-```bash
202202-sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
203203-```
204204-205205-##### Verify Docker Engine installation
176176+Using ssh on your server, use `pdsadmin` to create an account if you haven't already.
206177207178```bash
208208-sudo docker run hello-world
209209-```
210210-211211-#### Set up the PDS directory
212212-213213-```bash
214214-sudo mkdir /pds
215215-sudo mkdir --parents /pds/caddy/data
216216-sudo mkdir --parents /pds/caddy/etc/caddy
179179+sudo pdsadmin account create
217180```
218181219219-#### Create the Caddyfile
182182+### Creating an account using an invite code
220183221221-Be sure to replace `example.com` with your own domain.
184184+Using ssh on your server, use `pdsadmin` to create an invite code.
222185223186```bash
224224-cat <<CADDYFILE | sudo tee /pds/caddy/etc/caddy/Caddyfile
225225-{
226226- email you@example.com
227227- on_demand_tls {
228228- ask http://localhost:3000
229229- }
230230-}
231231-232232-*.example.com, example.com {
233233- tls {
234234- on_demand
235235- }
236236- reverse_proxy http://localhost:3000
237237-}
238238-CADDYFILE
187187+sudo pdsadmin create-invite-code
239188```
240189241241-#### Create the PDS env configuration file
190190+When creating an account using the app, enter this invite code.
242191243243-You should fill in the first 5 values, but leave the rest untouched unless you have good reason to change it.
192192+### Using the Bluesky app with your PDS
244193245245-See the PDS environment variables section at the end of this README for explanations of each value
246246-247247-Your PDS will need two secp256k1 private keys provided as hex strings. You can securely generate these keys using `openssl` with the following command:
248248-249249-**Note:**
250250-* Replace `example.com` with your domain name.
194194+You can use the Bluesky app to connect to your PDS.
251195252252-```bash
253253-PDS_HOSTNAME="example.com"
254254-PDS_JWT_SECRET="$(openssl rand --hex 16)"
255255-PDS_ADMIN_PASSWORD="$(openssl rand --hex 16)"
256256-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)"
257257-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)"
196196+1. Get the Bluesky app
197197+ * [Bluesky for Web](https://bsky.app/)
198198+ * [Bluesky for iPhone](https://apps.apple.com/us/app/bluesky-social/id6444370199)
199199+ * [Bluesky for Android](https://play.google.com/store/apps/details?id=xyz.blueskyweb.app)
200200+1. Enter the URL of your PDS (e.g. `https://example.com/`)
258201259259-cat <<PDS_CONFIG | sudo tee /pds/pds.env
260260-PDS_HOSTNAME=${PDS_HOSTNAME}
261261-PDS_JWT_SECRET=${PDS_JWT_SECRET}
262262-PDS_ADMIN_PASSWORD=${PDS_ADMIN_PASSWORD}
263263-PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX=${PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX}
264264-PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX=${PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX}
265265-PDS_DB_SQLITE_LOCATION=/pds/pds.sqlite
266266-PDS_BLOBSTORE_DISK_LOCATION=/pds/blocks
267267-PDS_DID_PLC_URL=https://plc.bsky-sandbox.dev
268268-PDS_BSKY_APP_VIEW_URL=https://api.bsky-sandbox.dev
269269-PDS_BSKY_APP_VIEW_DID=did:web:api.bsky-sandbox.dev
270270-PDS_CRAWLERS=https://bgs.bsky-sandbox.dev
271271-PDS_CONFIG
272272-```
202202+_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._
273203274274-#### Start the PDS containers
204204+### Setting up SMTP
275205276276-##### Download the Docker compose file
206206+To be able to verify users' email addresses and send other emails, you need to set up an SMTP server.
277207278278-Download the `compose.yaml` to run your PDS, which includes the following containers:
208208+One way to do this is to use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices.
279209280280-* `pds` Node PDS server running on http://localhost:3000
281281-* `caddy` HTTP reverse proxy handling TLS and proxying requests to the PDS server
282282-* `watchtower` Daemon responsible for auto-updating containers to keep the server secure and federating
210210+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):
283211284284-```bash
285285-curl https://raw.githubusercontent.com/bluesky-social/pds/main/compose.yaml | sudo tee /pds/compose.yaml
286212```
287287-288288-##### Create the systemd service
289289-290290-```bash
291291-cat <<SYSTEMD_UNIT_FILE | sudo tee /etc/systemd/system/pds.service
292292-[Unit]
293293-Description=Bluesky PDS Service
294294-Documentation=https://github.com/bluesky-social/pds
295295-Requires=docker.service
296296-After=docker.service
213213+PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:465/
214214+PDS_EMAIL_FROM_ADDRESS=admin@your.domain
215215+```
297216298298-[Service]
299299-Type=oneshot
300300-RemainAfterExit=yes
301301-WorkingDirectory=/pds
302302-ExecStart=/usr/bin/docker compose --file /pds/compose.yaml up --detach
303303-ExecStop=/usr/bin/docker compose --file /pds/compose.yaml down
217217+If you prefer to use a standard SMTP server (a local one or from your email provider), put your account's username and password in the URL:
304218305305-[Install]
306306-WantedBy=default.target
307307-SYSTEMD_UNIT_FILE
219219+```
220220+PDS_EMAIL_SMTP_URL=smtps://username:password@smtp.example.com/
308221```
309222310310-##### Start the service
223223+Alternatively, if you're running a local sendmail-compatible mail service like Postfix or Exim on the same host, you can configure the PDS to use the sendmail transport by using such URL:
311224312312-**Reload the systemd daemon to create the new service:**
313313-```bash
314314-sudo systemctl daemon-reload
315225```
316316-317317-**Enable the systemd service:**
318318-```bash
319319-sudo systemctl enable pds
226226+PDS_EMAIL_SMTP_URL=smtp:///?sendmail=true
320227```
321228322322-**Start the pds systemd service:**
323323-```bash
324324-sudo systemctl start pds
325325-```
229229+_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._
326230327327-**Ensure that containers are running**
231231+### Logging
328232329329-There should be a caddy, pds, and watchtower container running.
233233+By default, logs from the PDS are printed to `stdout` and end up in Docker's log. You can browse them by running:
330234331331-```bash
332332-sudo systemctl status pds
333235```
334334-335335-```bash
336336-sudo docker ps
236236+[sudo] docker logs pds
337237```
338238339339-### Verify your PDS is online
239239+Note: these logs are not persisted, so they will be lost after server reboot.
340240341341-You can check if your server is online and healthy by requesting the healthcheck endpoint.
241241+Alternatively, you can configure the logs to be printed to a file by setting `LOG_DESTINATION`:
342242343343-```bash
344344-curl https://example.com/xrpc/_health
345345-{"version":"0.2.2-beta.2"}
346243```
347347-348348-### Obtain your PDS admin password
244244+LOG_DESTINATION=/pds/pds.log
245245+```
349246350350-Your PDS admin password should be in your `pds.env` file if you used the installer script.
247247+You can also change the minimum level of logs to be printed (default: `info`):
351248352352-**For example:**
353353-354354-```bash
355355-$ source /pds/pds.env
356356-$ echo $PDS_ADMIN_PASSWORD
357357-a7b5970b6a5077bb41fc68a26d30adda
358249```
359359-### Generate an invite code for your PDS
360360-361361-By default, your PDS will require an invite code to create an account.
362362-363363-You can generate a new invite code with the following command:
364364-365365-```bash
366366-PDS_HOSTNAME="example.com"
367367-PDS_ADMIN_PASSWORD="<YOUR PDS ADMIN PASSWORD>"
368368-369369-curl --silent \
370370- --show-error \
371371- --request POST \
372372- --user "admin:${PDS_ADMIN_PASSWORD}" \
373373- --header "Content-Type: application/json" \
374374- --data '{"useCount": 1}' \
375375- https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createInviteCode
250250+LOG_LEVEL=debug
376251```
377252378378-**Note:** the `useCount` field specifies how many times an invite code can be used
253253+### Updating your PDS
379254380380-### Connecting to your server
255255+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.
381256382382-You can use the Bluesky app to connect to your server to create an account.
383383-384384-1. Get the Bluesky app
385385- * [Bluesky for Web (sandbox)](https://app.bsky-sandbox.dev/)
386386- * [Bluesky for iPhone](https://apps.apple.com/us/app/bluesky-social/id6444370199)
387387- * [Bluesky for Android](https://play.google.com/store/apps/details?id=xyz.blueskyweb.app)
388388-1. Enter the URL of your PDS (e.g. `https://example.com/`)
389389-1. Create an account using the generated invite code
390390-1. Create a post
391391-392392-_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._
393393-394394-Checkout [SANDBOX.md](./SANDBOX.md) for an overview of participating in the sandbox network.
395395-396396-### Manually updating your PDS
397397-398398-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.
399399-400400-**Pull the latest PDS container image:**
401257```bash
402402-sudo docker pull ghcr.io/bluesky-social/pds:latest
258258+sudo pdsadmin update
403259```
404260405405-**Restart PDS with the new container image:**
406406-```bash
407407-sudo systemctl restart pds
408408-```
409409-410410-## PDS environment variables
411411-412412-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.
261261+## License
413262414414-| Environment Variable | Value | Should update? | Notes |
415415-| ----------------------------------------- | ---------------------------- | -------------- | --------------------------------------------------------------------------- |
416416-| PDS_HOSTNAME | example.com | โ | Public domain you intend to deploy your service at |
417417-| PDS_JWT_SECRET | jwt-secret | โ | Use a secure high-entropy string that is 32 characters in length |
418418-| PDS_ADMIN_PASSWORD | admin-pass | โ | Use a secure high-entropy string that is 32 characters in length |
419419-| PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX | 3ee68... | โ | See above Generate Keys section - once set, do not change |
420420-| PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX | e049f... | โ | See above Generate Keys section - once set, do not change |
421421-| PDS_DB_SQLITE_LOCATION | /pds/pds.sqlite | โ | Or use `PDS_DB_POSTGRES_URL` depending on which database you intend to use |
422422-| PDS_BLOBSTORE_DISK_LOCATION | /pds/blocks | โ | Only update if you update the mounted volume for your docker image as well |
423423-| PDS_DID_PLC_URL | https://plc.bsky-sandbox.dev | โ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
424424-| PDS_BSKY_APP_VIEW_URL | https://api.bsky-sandbox.dev | โ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
425425-| PDS_BSKY_APP_VIEW_DID | did:web:api.bsky-sandbox.dev | โ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
426426-| PDS_CRAWLERS | https://bgs.bsky-sandbox.dev | โ | Do not adjust if you intend to federate with the Bluesky federation sandbox |
263263+This project is dual-licensed under MIT and Apache 2.0 terms:
427264428428-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.
265265+- MIT license ([LICENSE-MIT.txt](https://github.com/bluesky-social/pds/blob/main/LICENSE-MIT.txt) or http://opensource.org/licenses/MIT)
266266+- 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)
429267430430-Feel free to explore those [Here](https://github.com/bluesky-social/atproto/blob/main/packages/pds/src/config/env.ts). However, we will not be providing support for more advanced configurations.
268268+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.
-142
SANDBOX.md
···11-# Bluesky Developer Sandbox Guide
22-33-Welcome to the atproto federation developer sandbox!
44-55-This is a completely separate network from our production services that allows us to test out the federation architecture and wire protocol.
66-77-The federation sandbox environment is an area set up for exploration and testing of the technical components of the AT Protocol distributed social network. It is intended for developers and self-hosters to test out data availability in a federated environment.
88-99-To maintain a positive and productive developer experience, we've established this Code of Conduct that outlines our expectations and guidelines. This sandbox environment is initially meant to test the technical components of federation.
1010-1111-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.
1212-1313-# Guidelines that must be followed
1414-1515-Using the sandbox environment means you agree to adhere to our Guidelines. Please read the following carefully:
1616-1717-## Post responsibly
1818-1919-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.
2020-2121-Do not post content that requires active moderation or violates the [Bluesky Community Guidelines](https://bsky.social/about/support/community-guidelines).
2222-2323-## Keep the emphasis on testing
2424-2525-Weโre striving to maintain a sandbox environment that fosters learning and technical growth. We will defederate with instances that recruit users without making it clear that this is a test environment.
2626-2727-## Do limit account creation
2828-2929-We don't want any one server using a majority of the resources in the sandbox. To keep things balanced, to start, weโre only federating with Personal Data Servers (PDS) with up to 1000 accounts. However, we may change this if needed.
3030-3131-## Donโt expect persistence or uptime
3232-3333-We will routinely be wiping the data on our infrastructure. This is intended to reset the network state and to test sync protocols. Accounts and content should not be mirrored or migrated between the sandbox and real-world environments.
3434-3535-## Don't advertise your service as being "Bluesky"
3636-3737-This is a developer sandbox and is meant for technical users. Do not promote your service as being a way for non-technical users to use Bluesky.
3838-3939-## Do not mirror sandbox did:plcs to production
4040-4141-4242-## Status and Wipes
4343-4444-### ๐ย Beware of dragons!
4545-4646-This hasnโt been production tested yet. It seems to work pretty well, but who knows whatโs lurking under the surface โ that's what this sandbox is for! Have patience with us as we prep for federation.
4747-4848-On that note, please give us feedback either in [Issues](https://github.com/bluesky-social/atproto/issues) (actual bugs) or [Discussions](https://github.com/bluesky-social/atproto/discussions) (higher-level questions/discussions) on the [atproto repo](https://github.com/bluesky-social/atproto).
4949-5050-### Routine wipes
5151-5252-As part of the sandbox, we will be doing routine wipes of all network data.
5353-5454-We expect to perform wipes on a weekly or bi-weekly basis, though we reserve the right to do a wipe at any point.
5555-5656-When we wipe data, we will be wiping it on all services (BGS, App View, PLC). We will also mark any existing DIDs as โinvalidโ & will refuse to index those accounts in the next epoch of the network to discourage users from attempting to โrolloverโ their accounts across wipes.
5757-5858-# Getting started
5959-6060-For complete instructions on getting your PDS set up, check out the [README](./README.md).
6161-6262-To access your account, youโll log in with the client of your choice in the exact same way that you log into production Bluesky, for instance the [Bluesky web client](https://app.bsky-sandbox.dev/). When you do so, please provide the url of *your PDS* as the service that you wish to log in to.
6363-6464-## Auto-updates
6565-6666-Weโve included Watchtower in the PDS distribution. Every day at midnight PST, this will check our GitHub container registry to see if there is a new version of the PDS container & update it on your service.
6767-6868-This will allow us to rapidly iterate on protocol changes, as weโll be able to push them out to the network on a daily basis.
6969-7070-When we do routine network wipes, we will be pushing out a database migration to participating PDS that wipes content and accounts.
7171-7272-You are within your rights to disable Watchtower auto-updates, but we strongly encourage their use and will not be providing support if you decide not to run the most up-to-date PDS distribution.
7373-7474-## Odds & Ends & Warnings & Reminders
7575-7676-๐งช Experiment & have fun!
7777-7878-๐คย Run [feed generators](https://github.com/bluesky-social/feed-generator). They should work the exact same way as production - be sure to adjust your env to listen to Sandbox BGS!
7979-8080-๐ Feel free to run your own AppView or BGS - although itโs a bit more involved & weโll be providing limited support for this.
8181-8282-โ๏ธ Because the atproto network is a distributed system, your PDS can no longer definitively read-after-write. Updates are generally processed pretty quickly, however this discrepancy may show in certain circumstances, such as updating a profile or replying to a thread. We're working on utilities to make this easier to handle.
8383-8484-โฑ๏ธ As a specific case of the above, because we use on-demand TLS with Caddy, your profile may not load at first - please be patient & it should load within 5-10s after account creation. Again, we'll be working to smooth over this.
8585-8686-๐คย Your PDS will provide your handle by default. Custom domain handles should work exactly the same in sandbox as they do on production Bluesky. Although you will not be able to re-use your handle from production Bluesky as you can only have one DID set per handle.
8787-8888-โ ๏ธ If you follow the self-hosted PDS setup instructions, youโll have private key material in your env file - be careful about sharing that!
8989-9090-๐ฃย This is a sandbox version of a **public broadcast protocol** - please do not share sensitive information.
9191-9292-๐คย Help each other out! Respond to issues & discussions, chat in [Matrix](https://matrix.to/#/%23bluesky-dev:matrix.org) or the community-run [Discord](https://discord.gg/3srmDsHSZJ), etc.
9393-9494-# Learn more about atproto federation
9595-9696-Check out the [high-level view of federation](https://bsky.social/about/blog/5-5-2023-federation-architecture).
9797-9898-Dive deeper with the [atproto docs](https://atproto.com/docs).
9999-100100-## Network Services
101101-102102-We are running three services: PLC, BGS, Bluesky "App View"
103103-104104-### PLC
105105-106106-**Hostname:** `plc.bsky-sandbox.dev`
107107-108108-**Code:** https://github.com/bluesky-social/did-method-plc
109109-110110-PLC is the default DID provider for the network. DIDs are the root of your identity in the network. Sandbox PLC functions exactly the same as production PLC, but it is run as a separate service with a separate dataset. The DID resolution client in the self-hosted PDS package is set up to talk the correct PLC service.
111111-112112-### BGS
113113-114114-**Hostname:** `bgs.bsky-sandbox.dev`
115115-116116-**Code:** https://github.com/bluesky-social/indigo/tree/main/bgs
117117-118118-BGS (Big Graph Service) is the firehose for the entire network. It collates data from PDSs & rebroadcasts them out on one giant websocket.
119119-120120-BGS has to find out about your server somehow, so when we do any sort of write, we ping BGS with `com.atproto.sync.requestCrawl` to notify it of new data. This is done automatically in the self-hosted PDS package.
121121-122122-If youโre familiar with the Bluesky production firehose, you can subscribe to the BGS firehose in the exact same manner, the interface & data should be identical
123123-124124-### Bluesky App View
125125-126126-**Hostname:** `api.bsky-sandbox.dev`
127127-128128-**Code:** https://github.com/bluesky-social/atproto/tree/main/packages/bsky
129129-130130-The Bluesky App View aggregates data from across the network to service the Bluesky microblogging application. It consumes the firehose from the BGS, processing it into serviceable views of the network such as feeds, post threads, and user profiles. It functions as a fairly traditional web service.
131131-132132-When you request a Bluesky-related view from your PDS (`getProfile` for instance), your PDS will actually proxy the request up to App View.
133133-134134-Feel free to experiment with running your own App View if you like!
135135-136136-# The PDS
137137-138138-The PDS (Personal Data Server) is where users host their social data such as posts, profiles, likes, and follows. The goal of the sandbox is to federate many PDS together, so we hope youโll run your own.
139139-140140-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.
141141-142142-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.
···1818# The Docker compose file.
1919COMPOSE_URL="https://raw.githubusercontent.com/bluesky-social/pds/main/compose.yaml"
20202121+# The pdsadmin script.
2222+PDSADMIN_URL="https://raw.githubusercontent.com/bluesky-social/pds/main/pdsadmin.sh"
2323+2124# System dependencies.
2225REQUIRED_SYSTEM_PACKAGES="
2326 ca-certificates
2427 curl
2528 gnupg
2929+ jq
2630 lsb-release
2731 openssl
3232+ sqlite3
2833 xxd
2934"
3035# Docker packages.
3136REQUIRED_DOCKER_PACKAGES="
3737+ containerd.io
3238 docker-ce
3339 docker-ce-cli
3440 docker-compose-plugin
3535- containerd.io
3641"
37423843PUBLIC_IP=""
···4550PDS_DATADIR="${1:-/pds}"
4651PDS_HOSTNAME="${2:-}"
4752PDS_ADMIN_EMAIL="${3:-}"
4848-PDS_DID_PLC_URL="https://plc.bsky-sandbox.dev"
4949-PDS_BSKY_APP_VIEW_ENDPOINT="https://api.bsky-sandbox.dev"
5050-PDS_BSKY_APP_VIEW_DID="did:web:api.bsky-sandbox.dev"
5151-PDS_CRAWLERS="https://bgs.bsky-sandbox.dev"
5353+PDS_DID_PLC_URL="https://plc.directory"
5454+PDS_BSKY_APP_VIEW_URL="https://api.bsky.app"
5555+PDS_BSKY_APP_VIEW_DID="did:web:api.bsky.app"
5656+PDS_REPORT_SERVICE_URL="https://mod.bsky.app"
5757+PDS_REPORT_SERVICE_DID="did:plc:ar7c4by46qjdydhdevvrndac"
5858+PDS_CRAWLERS="https://bsky.network"
52595360function usage {
5461 local error="${1}"
···8693 elif [[ "${DISTRIB_CODENAME}" == "jammy" ]]; then
8794 SUPPORTED_OS="true"
8895 echo "* Detected supported distribution Ubuntu 22.04 LTS"
9696+ elif [[ "${DISTRIB_CODENAME}" == "mantic" ]]; then
9797+ SUPPORTED_OS="true"
9898+ echo "* Detected supported distribution Ubuntu 23.10 LTS"
8999 fi
90100 elif [[ "${DISTRIB_ID}" == "debian" ]]; then
91101 if [[ "${DISTRIB_CODENAME}" == "bullseye" ]]; then
···102112 exit 1
103113 fi
104114115115+ # Enforce that the data directory is /pds since we're assuming it for now.
116116+ # Later we can make this actually configurable.
117117+ if [[ "${PDS_DATADIR}" != "/pds" ]]; then
118118+ usage "The data directory must be /pds. Exiting..."
119119+ fi
120120+105121 # Check if PDS is already installed.
106122 if [[ -e "${PDS_DATADIR}/pds.sqlite" ]]; then
107123 echo
···124140 echo "For assistance, check https://github.com/bluesky-social/pds"
125141 exit 1
126142 fi
127127-128143129144 #
130145 # Attempt to determine server's public IP.
···166181167182 From your DNS provider's control panel, create the required
168183 DNS record with the value of your server's public IP address.
169169-184184+170185 + Any DNS name that can be resolved on the public internet will work.
171186 + Replace example.com below with any valid domain name you control.
172187 + A TTL of 600 seconds (10 minutes) is recommended.
173173-188188+174189 Example DNS record:
175175-190190+176191 NAME TYPE VALUE
177192 ---- ---- -----
178193 example.com A ${PUBLIC_IP:-Server public IP}
···213228 usage "No admin email specified"
214229 fi
215230216216-217231 #
218232 # Install system packages.
219233 #
···227241 sleep 2
228242 done
229243 fi
230230-244244+231245 apt-get update
232246 apt-get install --yes ${REQUIRED_SYSTEM_PACKAGES}
233247···295309{
296310 email ${PDS_ADMIN_EMAIL}
297311 on_demand_tls {
298298- ask http://localhost:3000
312312+ ask http://localhost:3000/tls-check
299313 }
300314}
301315···316330PDS_HOSTNAME=${PDS_HOSTNAME}
317331PDS_JWT_SECRET=$(eval "${GENERATE_SECURE_SECRET_CMD}")
318332PDS_ADMIN_PASSWORD=${PDS_ADMIN_PASSWORD}
319319-PDS_REPO_SIGNING_KEY_K256_PRIVATE_KEY_HEX=$(eval "${GENERATE_K256_PRIVATE_KEY_CMD}")
320333PDS_PLC_ROTATION_KEY_K256_PRIVATE_KEY_HEX=$(eval "${GENERATE_K256_PRIVATE_KEY_CMD}")
321321-PDS_DB_SQLITE_LOCATION=${PDS_DATADIR}/pds.sqlite
334334+PDS_DATA_DIRECTORY=${PDS_DATADIR}
322335PDS_BLOBSTORE_DISK_LOCATION=${PDS_DATADIR}/blocks
336336+PDS_BLOB_UPLOAD_LIMIT=52428800
323337PDS_DID_PLC_URL=${PDS_DID_PLC_URL}
324324-PDS_BSKY_APP_VIEW_ENDPOINT=${PDS_BSKY_APP_VIEW_ENDPOINT}
338338+PDS_BSKY_APP_VIEW_URL=${PDS_BSKY_APP_VIEW_URL}
325339PDS_BSKY_APP_VIEW_DID=${PDS_BSKY_APP_VIEW_DID}
340340+PDS_REPORT_SERVICE_URL=${PDS_REPORT_SERVICE_URL}
341341+PDS_REPORT_SERVICE_DID=${PDS_REPORT_SERVICE_DID}
326342PDS_CRAWLERS=${PDS_CRAWLERS}
343343+LOG_ENABLED=true
327344PDS_CONFIG
328345329346 #
···378395 fi
379396 fi
380397398398+ #
399399+ # Download and install pdadmin.
400400+ #
401401+ echo "* Downloading pdsadmin"
402402+ curl \
403403+ --silent \
404404+ --show-error \
405405+ --fail \
406406+ --output "/usr/local/bin/pdsadmin" \
407407+ "${PDSADMIN_URL}"
408408+ chmod +x /usr/local/bin/pdsadmin
409409+381410 cat <<INSTALLER_MESSAGE
382411========================================================================
383383-PDS installation successful!
412412+PDS installation successful!
384413------------------------------------------------------------------------
385414386415Check service status : sudo systemctl status pds
387416Watch service logs : sudo docker logs -f pds
388417Backup service data : ${PDS_DATADIR}
418418+PDS Admin command : pdsadmin
389419390420Required Firewall Ports
391421------------------------------------------------------------------------
···396426397427Required DNS entries
398428------------------------------------------------------------------------
399399-Name Type Value
429429+Name Type Value
400430------- --------- ---------------
401401-${PDS_HOSTNAME} A ${PUBLIC_IP}
402402-*.${PDS_HOSTNAME} A ${PUBLIC_IP}
431431+${PDS_HOSTNAME} A ${PUBLIC_IP}
432432+*.${PDS_HOSTNAME} A ${PUBLIC_IP}
403433404434Detected public IP of this server: ${PUBLIC_IP}
405435406406-# To create an invite code, run the following command:
407407-408408-curl --silent \\
409409- --show-error \\
410410- --request POST \\
411411- --user "admin:${PDS_ADMIN_PASSWORD}" \\
412412- --header "Content-Type: application/json" \\
413413- --data '{"useCount": 1}' \\
414414- https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createInviteCode
436436+To see pdsadmin commands, run "pdsadmin help"
415437416438========================================================================
417439INSTALLER_MESSAGE
440440+441441+ CREATE_ACCOUNT_PROMPT=""
442442+ read -p "Create a PDS user account? (y/N): " CREATE_ACCOUNT_PROMPT
443443+444444+ if [[ "${CREATE_ACCOUNT_PROMPT}" =~ ^[Yy] ]]; then
445445+ pdsadmin account create
446446+ fi
447447+418448}
419449420450# Run main function.
+234
pdsadmin/account.sh
···11+#!/bin/bash
22+set -o errexit
33+set -o nounset
44+set -o pipefail
55+66+PDS_ENV_FILE=${PDS_ENV_FILE:-"/pds/pds.env"}
77+source "${PDS_ENV_FILE}"
88+99+# curl a URL and fail if the request fails.
1010+function curl_cmd_get {
1111+ curl --fail --silent --show-error "$@"
1212+}
1313+1414+# curl a URL and fail if the request fails.
1515+function curl_cmd_post {
1616+ curl --fail --silent --show-error --request POST --header "Content-Type: application/json" "$@"
1717+}
1818+1919+# curl a URL but do not fail if the request fails.
2020+function curl_cmd_post_nofail {
2121+ curl --silent --show-error --request POST --header "Content-Type: application/json" "$@"
2222+}
2323+2424+# The subcommand to run.
2525+SUBCOMMAND="${1:-}"
2626+2727+#
2828+# account list
2929+#
3030+if [[ "${SUBCOMMAND}" == "list" ]]; then
3131+ DIDS="$(curl_cmd_get \
3232+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.sync.listRepos?limit=100" | jq --raw-output '.repos[].did'
3333+ )"
3434+ OUTPUT='[{"handle":"Handle","email":"Email","did":"DID"}'
3535+ for did in ${DIDS}; do
3636+ ITEM="$(curl_cmd_get \
3737+ --user "admin:${PDS_ADMIN_PASSWORD}" \
3838+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.admin.getAccountInfo?did=${did}"
3939+ )"
4040+ OUTPUT="${OUTPUT},${ITEM}"
4141+ done
4242+ OUTPUT="${OUTPUT}]"
4343+ echo "${OUTPUT}" | jq --raw-output '.[] | [.handle, .email, .did] | @tsv' | column --table
4444+4545+#
4646+# account create
4747+#
4848+elif [[ "${SUBCOMMAND}" == "create" ]]; then
4949+ EMAIL="${2:-}"
5050+ HANDLE="${3:-}"
5151+5252+ if [[ "${EMAIL}" == "" ]]; then
5353+ read -p "Enter an email address (e.g. alice@${PDS_HOSTNAME}): " EMAIL
5454+ fi
5555+ if [[ "${HANDLE}" == "" ]]; then
5656+ read -p "Enter a handle (e.g. alice.${PDS_HOSTNAME}): " HANDLE
5757+ fi
5858+5959+ if [[ "${EMAIL}" == "" || "${HANDLE}" == "" ]]; then
6060+ echo "ERROR: missing EMAIL and/or HANDLE parameters." >/dev/stderr
6161+ echo "Usage: $0 ${SUBCOMMAND} <EMAIL> <HANDLE>" >/dev/stderr
6262+ exit 1
6363+ fi
6464+6565+ PASSWORD="$(openssl rand -base64 30 | tr -d "=+/" | cut -c1-24)"
6666+ INVITE_CODE="$(curl_cmd_post \
6767+ --user "admin:${PDS_ADMIN_PASSWORD}" \
6868+ --data '{"useCount": 1}' \
6969+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createInviteCode" | jq --raw-output '.code'
7070+ )"
7171+ RESULT="$(curl_cmd_post_nofail \
7272+ --data "{\"email\":\"${EMAIL}\", \"handle\":\"${HANDLE}\", \"password\":\"${PASSWORD}\", \"inviteCode\":\"${INVITE_CODE}\"}" \
7373+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.server.createAccount"
7474+ )"
7575+7676+ DID="$(echo $RESULT | jq --raw-output '.did')"
7777+ if [[ "${DID}" != did:* ]]; then
7878+ ERR="$(echo ${RESULT} | jq --raw-output '.message')"
7979+ echo "ERROR: ${ERR}" >/dev/stderr
8080+ echo "Usage: $0 ${SUBCOMMAND} <EMAIL> <HANDLE>" >/dev/stderr
8181+ exit 1
8282+ fi
8383+8484+ echo
8585+ echo "Account created successfully!"
8686+ echo "-----------------------------"
8787+ echo "Handle : ${HANDLE}"
8888+ echo "DID : ${DID}"
8989+ echo "Password : ${PASSWORD}"
9090+ echo "-----------------------------"
9191+ echo "Save this password, it will not be displayed again."
9292+ echo
9393+9494+#
9595+# account delete
9696+#
9797+elif [[ "${SUBCOMMAND}" == "delete" ]]; then
9898+ DID="${2:-}"
9999+100100+ if [[ "${DID}" == "" ]]; then
101101+ echo "ERROR: missing DID parameter." >/dev/stderr
102102+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
103103+ exit 1
104104+ fi
105105+106106+ if [[ "${DID}" != did:* ]]; then
107107+ echo "ERROR: DID parameter must start with \"did:\"." >/dev/stderr
108108+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
109109+ exit 1
110110+ fi
111111+112112+ echo "This action is permanent."
113113+ read -r -p "Are you sure you'd like to delete ${DID}? [y/N] " response
114114+ if [[ ! "${response}" =~ ^([yY][eE][sS]|[yY])$ ]]; then
115115+ exit 0
116116+ fi
117117+118118+ curl_cmd_post \
119119+ --user "admin:${PDS_ADMIN_PASSWORD}" \
120120+ --data "{\"did\": \"${DID}\"}" \
121121+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.admin.deleteAccount" >/dev/null
122122+123123+ echo "${DID} deleted"
124124+125125+#
126126+# account takedown
127127+#
128128+elif [[ "${SUBCOMMAND}" == "takedown" ]]; then
129129+ DID="${2:-}"
130130+ TAKEDOWN_REF="$(date +%s)"
131131+132132+ if [[ "${DID}" == "" ]]; then
133133+ echo "ERROR: missing DID parameter." >/dev/stderr
134134+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
135135+ exit 1
136136+ fi
137137+138138+ if [[ "${DID}" != did:* ]]; then
139139+ echo "ERROR: DID parameter must start with \"did:\"." >/dev/stderr
140140+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
141141+ exit 1
142142+ fi
143143+144144+ PAYLOAD="$(cat <<EOF
145145+ {
146146+ "subject": {
147147+ "\$type": "com.atproto.admin.defs#repoRef",
148148+ "did": "${DID}"
149149+ },
150150+ "takedown": {
151151+ "applied": true,
152152+ "ref": "${TAKEDOWN_REF}"
153153+ }
154154+ }
155155+EOF
156156+)"
157157+158158+ curl_cmd_post \
159159+ --user "admin:${PDS_ADMIN_PASSWORD}" \
160160+ --data "${PAYLOAD}" \
161161+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.admin.updateSubjectStatus" >/dev/null
162162+163163+ echo "${DID} taken down"
164164+165165+#
166166+# account untakedown
167167+#
168168+elif [[ "${SUBCOMMAND}" == "untakedown" ]]; then
169169+ DID="${2:-}"
170170+171171+ if [[ "${DID}" == "" ]]; then
172172+ echo "ERROR: missing DID parameter." >/dev/stderr
173173+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
174174+ exit 1
175175+ fi
176176+177177+ if [[ "${DID}" != did:* ]]; then
178178+ echo "ERROR: DID parameter must start with \"did:\"." >/dev/stderr
179179+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
180180+ exit 1
181181+ fi
182182+183183+ PAYLOAD=$(cat <<EOF
184184+ {
185185+ "subject": {
186186+ "\$type": "com.atproto.admin.defs#repoRef",
187187+ "did": "${DID}"
188188+ },
189189+ "takedown": {
190190+ "applied": false
191191+ }
192192+ }
193193+EOF
194194+)
195195+196196+ curl_cmd_post \
197197+ --user "admin:${PDS_ADMIN_PASSWORD}" \
198198+ --data "${PAYLOAD}" \
199199+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.admin.updateSubjectStatus" >/dev/null
200200+201201+ echo "${DID} untaken down"
202202+#
203203+# account reset-password
204204+#
205205+elif [[ "${SUBCOMMAND}" == "reset-password" ]]; then
206206+ DID="${2:-}"
207207+ PASSWORD="$(openssl rand -base64 30 | tr -d "=+/" | cut -c1-24)"
208208+209209+ if [[ "${DID}" == "" ]]; then
210210+ echo "ERROR: missing DID parameter." >/dev/stderr
211211+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
212212+ exit 1
213213+ fi
214214+215215+ if [[ "${DID}" != did:* ]]; then
216216+ echo "ERROR: DID parameter must start with \"did:\"." >/dev/stderr
217217+ echo "Usage: $0 ${SUBCOMMAND} <DID>" >/dev/stderr
218218+ exit 1
219219+ fi
220220+221221+ curl_cmd_post \
222222+ --user "admin:${PDS_ADMIN_PASSWORD}" \
223223+ --data "{ \"did\": \"${DID}\", \"password\": \"${PASSWORD}\" }" \
224224+ "https://${PDS_HOSTNAME}/xrpc/com.atproto.admin.updateAccountPassword" >/dev/null
225225+226226+ echo
227227+ echo "Password reset for ${DID}"
228228+ echo "New password: ${PASSWORD}"
229229+ echo
230230+231231+else
232232+ echo "Unknown subcommand: ${SUBCOMMAND}" >/dev/stderr
233233+ exit 1
234234+fi
···11+#!/bin/bash
22+set -o errexit
33+set -o nounset
44+set -o pipefail
55+66+# This script is used to display help information for the pdsadmin command.
77+cat <<HELP
88+pdsadmin help
99+--
1010+update
1111+ Update to the latest PDS version.
1212+ e.g. pdsadmin update
1313+1414+account
1515+ list
1616+ List accounts
1717+ e.g. pdsadmin account list
1818+ create <EMAIL> <HANDLE>
1919+ Create a new account
2020+ e.g. pdsadmin account create alice@example.com alice.example.com
2121+ delete <DID>
2222+ Delete an account specified by DID.
2323+ e.g. pdsadmin account delete did:plc:xyz123abc456
2424+ takedown <DID>
2525+ Takedown an account specified by DID.
2626+ e.g. pdsadmin account takedown did:plc:xyz123abc456
2727+ untakedown <DID>
2828+ Remove a takedown from an account specified by DID.
2929+ e.g. pdsadmin account untakedown did:plc:xyz123abc456
3030+ reset-password <DID>
3131+ Reset a password for an account specified by DID.
3232+ e.g. pdsadmin account reset-password did:plc:xyz123abc456
3333+3434+request-crawl [<RELAY HOST>]
3535+ Request a crawl from a relay host.
3636+ e.g. pdsadmin request-crawl bsky.network
3737+3838+create-invite-code
3939+ Create a new invite code.
4040+ e.g. pdsadmin create-invite-code
4141+4242+help
4343+ Display this help information.
4444+4545+HELP
···11+#!/bin/bash
22+set -o errexit
33+set -o nounset
44+set -o pipefail
55+66+PDS_DATADIR="/pds"
77+COMPOSE_FILE="${PDS_DATADIR}/compose.yaml"
88+COMPOSE_URL="https://raw.githubusercontent.com/bluesky-social/pds/main/compose.yaml"
99+1010+# TODO: allow the user to specify a version to update to.
1111+TARGET_VERSION="${1:-}"
1212+1313+COMPOSE_TEMP_FILE="${COMPOSE_FILE}.tmp"
1414+1515+echo "* Downloading PDS compose file"
1616+curl \
1717+ --silent \
1818+ --show-error \
1919+ --fail \
2020+ --output "${COMPOSE_TEMP_FILE}" \
2121+ "${COMPOSE_URL}"
2222+2323+if cmp --quiet "${COMPOSE_FILE}" "${COMPOSE_TEMP_FILE}"; then
2424+ echo "PDS is already up to date"
2525+ rm --force "${COMPOSE_TEMP_FILE}"
2626+ exit 0
2727+fi
2828+2929+echo "* Updating PDS"
3030+mv "${COMPOSE_TEMP_FILE}" "${COMPOSE_FILE}"
3131+3232+echo "* Restarting PDS"
3333+systemctl restart pds
3434+3535+cat <<MESSAGE
3636+PDS has been updated
3737+---------------------
3838+Check systemd logs: journalctl --unit pds
3939+Check container logs: docker logs pds
4040+4141+MESSAGE
+30
pdsadmin.sh
···11+#!/bin/bash
22+set -o errexit
33+set -o nounset
44+set -o pipefail
55+66+PDSADMIN_BASE_URL="https://raw.githubusercontent.com/bluesky-social/pds/main/pdsadmin"
77+88+# Command to run.
99+COMMAND="${1:-help}"
1010+shift || true
1111+1212+# Ensure the user is root, since it's required for most commands.
1313+if [[ "${EUID}" -ne 0 ]]; then
1414+ echo "ERROR: This script must be run as root"
1515+ exit 1
1616+fi
1717+1818+# Download the script, if it exists.
1919+SCRIPT_URL="${PDSADMIN_BASE_URL}/${COMMAND}.sh"
2020+SCRIPT_FILE="$(mktemp /tmp/pdsadmin.${COMMAND}.XXXXXX)"
2121+2222+if ! curl --fail --silent --show-error --location --output "${SCRIPT_FILE}" "${SCRIPT_URL}"; then
2323+ echo "ERROR: ${COMMAND} not found"
2424+ exit 2
2525+fi
2626+2727+chmod +x "${SCRIPT_FILE}"
2828+if "${SCRIPT_FILE}" "$@"; then
2929+ rm --force "${SCRIPT_FILE}"
3030+fi