Skip to main content

Setting up an AT Protocol PDS on Coolify

I've fallen deep into the self-hosting, own your data, rabbit-hole, which led me to set up a Coolify instance on an Azure VPS. Coolify is running this very website you're reading right now, along with Umami, Forgejo, Linkding, and a variety of other services. As of this weekend, it's also running my AT Protocol Personal Data Server (PDS).

What is a PDS, and why should I run one?

In one sentence, a PDS is your personal data server on the AT Protocol. Think of it as owning your social media data instead of renting space on someone else's platform.[1]

To dig deeper into the what and why of a PDS, I'd highly recommend Dan Abramov's recent post "Open Social" which is what piqued my interest in the AT Protocol and running a PDS in the first place. It's well worth a read, even if you — like me — aren't a Bluesky user and don't intend to be.

Prerequisites

  • A running Coolify instance
  • A domain name
  • Basic familiarity with Docker/environment variables
  • Email service. I used Resend as it was fast and free to set up an account.

Setting up the PDS on Coolify

Setting the PDS up promised to be as straightforward as creating a new project on my Coolify instance, adding the "Bluesky PDS" service, and pressing deploy. It turns out, however, that Coolify's Bluesky PDS template has some issues which prevent it from (checks notes) working.

Fortunately, a kind soul has taken it upon themselves to fix the broken template. Their PR hasn't been merged at the time of writing, so I grabbed the Docker Compose from their PR and pasted that into a new Coolify "Docker Compose Empty" service. You should be able to skip this manual copy/paste entirely once the aforementioned PR has been merged, instead simply selecting "Bluesky PDS" from the list of available services in Coolify.

Once the service is set up, you'll need to add a handful of environment variables to get everything working smoothly.

  • SERVICE_FQDN_PDS, SERVICE_FQDN_PDS_3000. These should get populated automatically with the domain you assign to the PDS service in Coolify, but keep an eye on SERVICE_FQDN_PDS_3000 as that didn't automatically change when I changed the domain, which caused me some issues later down the line when trying to create an account. Both of these variables should be set to your domain (without the protocol) e.g., social.farrant.me.
  • PDS_EMAIL_FROM_ADDRESS, PDS_EMAIL_SMTP_URL. Email credentials grabbed from Resend after setting up a free account; required for account creation and password reset functionality.

Once they're set, hit deploy and — with any luck — your new PDS should be running on your chosen domain. If you visit your chosen domain in your browser and see some ASCII art, congratulations! You are now the proud owner of an AT Protocol Personal Data Server.

Once the sheer, unbridled elation of that moment has subsided you may, as I did, ask yourself "Now what?". We've got a PDS running, but how do we interact with it? How do we create an account?

Using your PDS

The first thing we should do is create an account on our PDS. Head over to the Terminal tab in Coolify and run the following.

/usr/local/bin/pdsadmin help

You'll be presented with a list of available admin commands you can use to set up your account on your PDS. To create your account run:

/usr/local/bin/pdsadmin account create

When prompted, enter your email address and chosen handle, ensuring your handle is in the format [handle].[your-pds-domain]. In my case, my PDS runs on social.farrant.me, so I would enter something like josh.social.farrant.me. If successful, you'll be presented with your DID and password, which you'll need to make a note of.

At this point, we should probably let people know we exist by running:

/usr/local/bin/pdsadmin request-crawl

Testing your PDS

Armed with your new account details, head over to bsky.app and sign in with your handle and password. Make sure to select a "Custom" domain and enter your PDS's domain.

Congratulations again! You're logged in to Bluesky using an account stored on your own PDS! Set up your profile, post something, or change your handle, then head over to Taproot AT Protocol Explorer and enter your DID. You should see all the data associated with your account being pulled from your PDS. Next head over to another service on the AT Protocol network — say frontpage.fyi — sign in, and upvote a post. Heading back to Taproot, you should see a new fyi.unravel collection on your PDS which contains a fyi.unravel.frontpage.vote. A third-party service has successfully written data to your PDS; that's cool, right?

At this point you're good to go. You've got a PDS running on your server, on your own domain, and you've successfully tested it with two services on the AT Protocol network. Go forth and federate!

  1. That was two sentences. ↩︎