Bluesky, one of the new Social Network contenders, recently made its first steps towards becoming properly federated with the launch of a self hosted option for the Personal Data Server. In other words, if you create an account on the PDS, all of your posts, media etc on Bluesky will ultimately be hosted on the PDS meaning that you, or another party you trust, hold the keys to your data. Migration of an existing account off bluesky servers and onto a PDS is possible, but currenly filled with so many disclaimers it’s probably not worth looking at in any serious manner yet.
It’s important to note that Bluesky themselves say that the PDS is not yet stable, and definitely not ready for prime time. That said, I set one up for a test account and from being in the Discord server for PDS admins (link on the main PDS github) it seems like there’s some common pain points if you’re doing something more complex that the automated installer can’t handle. Thus…. my troubleshooting guide.
I’m assuming you’ve already run through the setup guide on the repo and somethings gone wrong.
I suggest running through each section in turn, making sure each test works. For each domain I’ll be using example.com as the PDS domain. Substitute your PDSes own domain. Example responses are cribbed from my live PDS, slightly adjusted to make it clear which parts will be different.
HTTPS Connectivity to XRPC
The PDS requires that the following traffic is forwarded to it. These calls can be tried in your web browser of choice.
- Call
https://pds.example.com/xrpc/_health
This call should return some simple JSON showing the version of the PDS code you are running, e.g. {"version":"0.4.12"}
If this call fails with an HTTPS error, then you need to double check that your TLS Certificate is valid your your PDS domain such as example.com.
If this call fails with a 503 error ro a similar 5xx error, then it is likely that your reverse proxy isn’t able to talk to your PDS application / container. Double check your reverse proxy configuration for how it’s talking to the PDS. For example it should be sending traffic to the PDS on port 3000.
If you get a 404 error, then check that your reverse proxy is correctly forwarding all /xrpc path traffic to the PDS.
Websocket Connectivity
The PDS requires that websocket connections are correctly Upgraded and forwarded by your reverse proxy. Not every reverse proxy handles this by default, and this seems to be a common pitfall for people going off the ‘golden path’ that the DPS documentation describes.
- Get yourself a websocket client. EG in a browser extnesion (I use https://addons.mozilla.org/en-US/firefox/addon/simple-websocket-client/), or a CLI client if you prefer.
- Issue a websocket call to
wss://example.com/xrpc/com.atproto.sync.subscribeReposthis should result in an open websocket connection.
If you enocunter problems here you need to look up how to correctly handle websockets with your Reverse Proxy, e.g. using the information at http://nginx.org/en/docs/http/websocket.html for NGINX.
Request Federation at this point
At this point we’ve checked as much as we can config wise without an account on the PDS to test with. I would really recommend subimtting your federation request at this point and waiting for it to be approved, if you haven’t already. As the rest of the troubleshooting requires an account, and not being federated yet can lead to spurious problems as the bsky network will refuse to talk to your PDS properly.
Request a crawl at this point
Now that you are federated, you should request a crawl, especially if you were federated prior to finding this guide and you have fixed a problem.
- Use the
pdsadmin request-crawlcommand. Or take a look at the commands source and manually craft the curl request to your instance
HTTPS Connectivity to your PDSs subdomains
To support accounts being created using the subdomain of your PDS – which is how all the bsky apps require you sto sign up right now, it is important that you are correctly able to handle requests to subdomains. We’ll be using a freshly created account here, to ensure that the actual contents should be valid.
- Create an account on your pds. eg with
pdsadmin account createor, as above, look at the commands source and manually craft the curl request- Note that the chosen handle must not contain any terms in the reserved list
- Visit https://bsky-debug.app/handle and enter
youraccount.example.comand check that it shows as being valid by the HTTP method. You can ignore the DNS method for this test.
If it shows a TLS error, then ensure that your reverse proxy has a TLS Certificate configured for *.example.com to be used on all subdomains of example.com; or that it can get certificates for subdomains of example.com on demand (such as caddy does)
If you are getting a 404 error then ensure the following is setup
- traffic for
*.example.comis being forwarded to the PDS - traffic for
.well-known/atproto-didis being forwarded to the PDS
If you are still having problems try loading https://youraccount.example.com/.well-known/atproto-did in your web browser yourself. You should receive back something like did:plc:abc123def456ghi789
One final test to close the loop on the account
One final test would be to call https://example.com/xrpc/com.atproto.repo.describeRepo?repo=did:plc:abc123def456ghi789 in your web browser, using the did that matches the account you made in the last step. This should return a JSON document containing a bunch of information about your did, including that the handle is youraccount.example.com.
That’s all folks
That’s all I’ve got. By my understanding if everything I’ve described here is working then your PDS is properly working and you should be able to do anything you want through the bsky clients, including changing your handle. I’ll be keeping an eye on the PDS Admin discord, and may update this as I see other pain points that people going off the golden path hit, and ways to trobuleshoot them.