@hipauls.com blogs [Find me on Bluesky]

Self-Hosting Bluesky PDS with Nginx and Your Own Domain

December 1, 2024 (updated February 23, 2025)

This will create a Bluesky Personal Data Server (PDS) on a virtual private server (VPS). You will need to register your own domain, and we will use that as your new Bluesky handle. This veers off from the usual installation instructions a bit. Specifically, this tutorial is for people using Nginx as a reverse proxy already. The Bluesky PDS installer uses Caddy instead.

H/t to cprimozic.net, Rafael Eyng and u/jouste. Couldn't have created this server without tips from their blogs/posts.

Changes to usual install

  • Need/prefer Nginx over Caddy
  • If not using UFW, will need to temporarily switch
  • Need to explicitly state email/SMTP settings
  • Domain verifcation buggy for using domain as handle, will modify code

Third Party Vendors

I do not make money off of any of these companies. I name them only because I used them. Feel free to use any vendor you want.

  • DNS Registrar: Namecheap
  • Virtual Private Server: Vultr (Regular Cloud Compute)

Bluesky PDS Server Recommendations

This is taken directly from the official Bluesky PDS Github (https://github.com/bluesky-social/pds).

  • OS: Ubuntu 22.04
  • Memory RAM: 1 GB
  • CPU Cores: 1
  • Storage: 20 GB

Cloud VPS and Domain Registrar Setup

Be sure to register a domain. Once it is registered, you will need to create the DNS records. Be sure to use your own domain and your own IP address in all the examples in this blog. In the examples below, each line is given as host, record type, IP address.

  • @, A, 66.42.74.39
  • *, A, 66.42.74.39

Create your Ubuntu 22.04 cloud VPS. I have a barebones mail (SMTP/IMAP) server set up. And so I made sure the VPS has a PTR (or reverse DNS) record pointing to mail.hipauls.com. Ignore this step if you will use Resend or SendGride, as mentioned in the official Bluesky PDS Github documentation.

Remote Access onto Server and Prepare System

Open a terimnal or use Putty to SSH onto the VPS. When you first login as root onto your VPS, you'll be creating your own account. Don't forget to give yourself sudo privileges.

Be sure to harden SSH access by using keys, no password authentication, no root authentication, only allow specific users. I'd recommend specifying which ports you want available to the public and using something like Fail2Ban.

We have to make sure conflicting services are off and appropriate ones are on. Otherwise, the installer will error out. I use nftables as a firewall. However, Bluesky PDS installer uses ufw. When I initially created my VPS, I stopped and disabled ufw when setting up nftables.

Whichever firewall you use, be sure to open ports 80 and 443 to allow public connections to Bluesky PDS. This traffic is reverse proxied into the Docker PDS image at localhost:3000 by default.

If you're already using ufw firewall, then ignore the following step.

sudo service ufw start

We need to temporarily disable Nginx, because Bluesky PDS installer uses Caddy as the reverse proxy service. Later on, we'll bring Nginx back up and disable Caddy.

sudo service nginx stop

Bluesky PDS Install and Initial Setup

Download the installer file in your home directory. After modifying file's permissions, run the file as sudo.

cd ~
wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
chmod 774 ~/installer.sh
sudo ~/installer.sh

Create the initial account. The PDS requires the account handle to be in the form of @name.domain.com. As you know, we want our handle to be @domain.com and not @name.domain.com. This is okay, we'll change this later.

sudo pdsadmin account create

The values for email and handle name below are examples. Use your own, of course.

  • email: hipauls@hipauls.com
  • handle: hipauls.hipauls.com

The following output will be given if successfully created. Be sure to save this!

Account created successfully!
-----------------------------
Handle   : hipauls.hipauls.com
DID      : did:xyz:random-string
Password : random-password
-----------------------------
Save this password, it will not be displayed again.

Modify Bluesky PDS and System Setup

One of the main goals of this endeavor is to keep Nginx as reverse proxy. The PDS installer uses Caddy, and so we'll have to disable that. The installer also brings in an auto-updater, which will likely break our system. Bluesky PDS does a weird verification of handle that won't let you use root domain as your handle. This was our other main goal. Let's fix all this.

Bluesky PDS uses Docker to manage these services. We have to modify compose.yaml, where these services are declared.

sudo cp /pds/compose.yaml /pds/compose.yaml.bak && sudo nano /pds/compose.yaml

I modified the file's contents to the following. Pretty much just delete the other services.

version: '3.9'
services:
  pds:
    container_name: pds
    image: ghcr.io/bluesky-social/pds:0.4
    network_mode: host
    restart: unless-stopped
    volumes:
      - type: bind
        source: /pds
        target: /pds
    env_file:
      - /pds/pds.env

Stop and remove the Caddy and auto-update services.

sudo docker stop caddy
sudo docker rm caddy
sudo docker stop watchtower
sudo docker rm watchtower

For new account/handle verification on Bluesky, we need to define our email setup. For those following the recommendations from official Bluesky PDS Github documentation, I leave this up to you. For me, I used my self-hosted mail server. My SMTP service only listens for STARTTLS on port 587 (not implicit SSL). Follow along if you have a similar mail setup.

sudo cp /pds/pds.env /pds/pds.env.bak && sudo nano /pds/pds.env

I added the following lines to the bottom of the file. Be sure to use your own information.

PDS_SERVICE_HANDLE_DOMAINS=.hipauls.com
PDS_EMAIL_SMTP_URL=smtp://hipauls@hipauls.com:[yourpassword]@mail.hipauls.com:587/
PDS_EMAIL_FROM_ADDRESS=hipauls@hipauls.com

The PDS system validates account/handle name changes. It's very odd that the validation code won't allow root domain handles. For example, we had to create the account/handle @hipauls.hipauls.com. But when we try to change it to just @hipauls.com, the website throws an error. One of the h/t I mentioned above gave me the answer. The lines below will search for the line of code of interest, which we will comment out.

sudo docker exec -it pds sh
grep -r "Unable to resolve handle" . # look for the one with @atproto/pds/dist/
apk add nano
nano ./node_modules/.pnpm/@atproto+pds@0.4.74/node_modules/@atproto/pds/dist/api/com/atproto/identity/resolveHandle.js

Comment out the following line.

//throw new xrpc_server_1.InvalidRequestError('Unable to resolve handle');

Restart the PDS Docker image.

sudo docker compose -f /pds/compose.yaml down
sudo docker compose -f /pds/compose.yaml up -d

Modify Nginx for PDS Reverse Proxy

My domain hosts several websites that I use privately and just one publicly (https://www.hipauls.com). This works well with Bluesky PDS, because they just need access to the root domain, e.g., http://hipauls.com (port 80) and https://hipauls.com (port 443). The PDS docker image listens on localhost:3000. I use Let's Encrypt/Certbot for my site's SSL certificates. Before I show you the Nginx server definitions, we have to declare a variable to allow Websocket handling.

sudo nano /etc/nginx/nginx.conf
##
# Added for Bluesky PDS Reverse Proxy. Define $connection_upgrade for WebSocket handling
##
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

Here are the Nginx server definitions that handle my usual website and the PDS reverse proxy.

sudo nano /etc/nginx/sites-enabled/default
server {
  listen 80;
  listen [::]:80;
  server_name www.hipauls.com 66.42.74.39;
  # Let's Encrypt Challenge
  location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    root /var/www/html;
  }
  # Redirect to encrypted connection. Public site, not Bluesky PDS.
  location / { return 301 https://www.hipauls.com$request_uri; }
}
server {
  listen 80;
  listen [::]:80;
  server_name hipauls.com;
  # Let's Encrypt Challenge
  location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    root /var/www/html;
  }

  ######################################################################
  # Bluesky PDS reverse proxy.
  location ^~ /xrpc/ {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
  location ^~ /.well-known/atproto-did {
    proxy_pass http://localhost:3000/.well-known/atproto-did;
    proxy_set_header Host $host;
  }
  ######################################################################

  # Redirect to encrypted connection.
  location / { return 301 https://hipauls.com$request_uri; }
}
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name hipauls.com;
  ssl_certificate /etc/letsencrypt/live/www.hipauls.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/www.hipauls.com/privkey.pem;
  ssl_trusted_certificate /etc/letsencrypt/live/www.hipauls.com/chain.pem;
  ssl_dhparam /etc/ssl/private/dhparam.pem;
  ssl_stapling on;
  ssl_stapling_verify on;
  include /etc/nginx/certbot-ssl.conf;

  ######################################################################
  # Bluesky PDS reverse proxy.
  location ^~ /xrpc/ {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }
  location ^~ /.well-known/atproto-did {
    proxy_pass http://localhost:3000/.well-known/atproto-did;
    proxy_set_header Host $host;
  }
  ######################################################################

  # If traffic is not for Bluesky PDS, then redirect to public site.
  location / { return 301 https://www.hipauls.com$request_uri; }
}
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name www.hipauls.com;
  ssl_certificate /etc/letsencrypt/live/www.hipauls.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/www.hipauls.com/privkey.pem;
  ssl_trusted_certificate /etc/letsencrypt/live/www.hipauls.com/chain.pem;
  ssl_dhparam /etc/ssl/private/dhparam.pem;
  ssl_stapling on;
  ssl_stapling_verify on;
  include /etc/nginx/certbot-ssl.conf;

  # Security headers
  add_header X-Frame-Options SAMEORIGIN;
  add_header X-Content-Type-Options nosniff;
  add_header X-XSS-Protection "1; mode=block";

  # Basic settings for www public subdomain.
  ...
}

Now that Nginx is properly configured, let's put the system services we had previously changed to their original state. If you do use UFW and not another firewall, skip the UFW step.

sudo service ufw stop
sudo service nginx start

Test the connection by going to this website in any browser. Use your own domain, of course.

http://hipauls.com/xrpc/com.atproto.server.describeServer

Validate and Change Bluesky Handle to Domain

In your browser, launch https://bsky.app and click on Sign in. Click in Hosting provider and select Custom. Type your domain, e.g., hipauls.com, and click Done. Remember the account/handle we created earlier? Login using those credentials, e.g., @hipauls.hipauls.com and respective password generated by the PDS command.

With the initial login, you should get a pop-up window verifying your account via email. I didn't know how important it was to correctly set up the PDS environment SMTP variables. I kept waiting for the verification email for like 2 days thinking it was going to be sent by the main bsky servers. The email actually comes from your self-hosted Bluesky PDS. If you set up the SMTP variables correctly, you'll get the verification code by email.

The PDS needs to verify we actually do own the domain before it allows us to change the handle to the root domain. The domain registrar's DNS entry that the PDS uses for verification is obtained from app interface (not terminal cli). Click on Settings > Account > Handle > I have my own domain. Type in your domain up top, e.g., hipauls.com.

Log into your domain regisrar (I use Namecheap). Enter the TXT record given in the Bluesky app. It should look something like this.

Host: _atproto
Type: TXT
Value: did=did:xyz:random-string

Give it a few minutes to be pushed out into the world wide web. Remember the modification to PDS code we did earlier? I got stuck here for a while, because without the modification I kept getting an error. After the modification, clicking Verify DNS Record finally worked! And ta-da ... your Bluesky handle is now your root domain!

I hope you found this helpful. I spent my Thanksgiving food hangover working on this.

© 2024 @hipauls