Sammy Thomas

Table of Contents

Setting up Bluesky PDS

I recently decided to setup a Bluesky account and of course wanted to play around with hosting your own data. Mainly because it's cool that you can :)

The official instructions for how to do this are here: https://atproto.com/guides/self-hosting. They are good, but assume that you are using Ubuntu and not already using Caddy. In my case, I'm running Fedora on my server and am using Caddy already to manage my website. Fortunately, it is not too hard to modify their installation scripts to work on other operating systems and you can easily modify your Caddy config to support the Bluesky PDS.

I thought that I couldn't be the only one in this situation, so decided to record what I did in case it can speed up the process for somebody else.

I've posted a modified version of their script here, which you may be able to just use. The rest of this post describes how I modified the original scripts, and may be useful if my versions don't just work.

Modifying the original setup script

The installer.sh script does the work of installing and configuring everything. I started by ripping out all of the bits that dealt with checking the operating systems and installing dependencies through apt.

This means that you will be responsible for installing the following dependencies: 

ca-certificates
curl
gnupg
jq
lsb-release
openssl
sqlite3
xxd

And installing and setting up docker. I simply following the Docker installation instructions for my operating system here. These are the required Docker packages: 

containerd.io
docker-ce
docker-ce-cli
docker-compose-plugin

If you want to use their Caddy configuration, that should be all that you need to do. Just run the script.

Rolling your own Caddy configuration

Changing the docker compose configuration

If you want to roll your own Caddy configuration, then you have to do a few more things. I ripped out the Caddy configuration section from the installation script and then ran it.

Then have to modify the /pds/compose.yaml script to not start a Caddy service for us. Restart the pds service (which manages starting the Docker container) and that should be it for running the pds server locally. 

sudo systemctl restart pds

Updating your Caddyfile

I already had a Caddyfile configuring my website. Configuring it to work with the bluesky pds was the trickiest bit to figure out, but turned out to be pretty simple in the end.

My Caddy configuration for the main part of my website looked like this: 

sgt-pl.com {
    handle {
        # set the root of where we are serving files from
        root * /var/www/html

        # Enable the static file server.
        file_server
    }
}

I had to add a handle block that directs /xrpc requests to the local server running in the Docker container. The resulting configuration looks like this: 

sgt-pl.com {
    # setup xrpc to point to the bluesky pds server running on port 3000
    handle /xrpc/* {
        reverse_proxy http://localhost:3000
    }

    handle {
        # set the root of where we are serving files from
        root * /var/www/html

        # Enable the static file server.
        file_server
    }
}

This just instructs caddy to redirect all sgt-pl.com/xrpc/* requests to the Docker container. If you want to use your domain as your handle, you can also add this block to your website configuration: 

handle /.well-known/atproto-did {
    respond "<your_did>"
}

Your did is discoverable with sudo pdsadmin account list.

After you make changes to the configuration, you might need to restart Caddy: 

sudo systemctl restart caddy

Firewall setup

You'll also need to configure your firewall to allow traffic through port 80 and 443. I'm using the default firewall that is shipped with Fedora. The commands for configuring the proper ports are: 

sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --add-port=443/tcp --permanent
sudo firewall-cmd --reload

If you use something different, you'll have to refer to their documentation.

Email Verification Setup

You have to do some special things to get email verification setup. The instructions for this are listed in the README for the pds. I used the free tier of resend.com. The setup basically involves adding some DNS records. Resend is good at walking you through how this works.

Once you've done that, you have to set these variables in the /pds/pds.env file: 

PDS_EMAIL_SMTP_URL=smtps://resend:<your api key here>@smtp.resend.com:2465/
PDS_EMAIL_FROM_ADDRESS=admin@your.domain

Make sure that TCP traffic is allowed through port 2465 in your firewall. Finally you have to restart the pds server so that it picks up the env vars change: 

sudo systemctl restart pds

Some debugging notes

If something isn't working properly, it's useful to check the Docker logs. First find the id of the container running the pds server: 

sudo docker ps

And then with the CONTAINER ID in hand: 

sudo docker logs -n 10 $CONTAINER_ID

These logs can be a bit noisy to look through, but it's all JSON so jq is your friend. I also found that it's sometimes useful to just start the docker container manually so that you can attach to it easily, and it makes it easier to see logs.

Happy sailing through the Bluesky!