These are the steps I followed to get a working bluesky PDS instance installed and running, starting from a fresh install of Ubuntu 22.04.  There may be better ways, but this is what worked for me.

while it is technically possible to migrate an existing handle (bsky.social or custom domain) to a PDS using goat, it's a potentially identity-destroying process if something goes wrong. all this to say - don't expect to migrate your main identity over to your PDS. at least not yet.

 

assumptions

you will need a public IPv4 address, public DNS name, and allow incoming connections to ports 80 and 443 on tcp.

there's a de facto requirement for outgoing mail access.  this is for account setup verification emails.  i used resend and twiddled with ports until i found something that works.  this is what took the most time for me.

prereqs - Go

download package, extract and install, add Go to PATH

wget https://go.dev/dl/go1.23.3.linux-amd64.tar.gz 
sudo tar -C /usr/local -xzf go1.23.3.linux-amd64.tar.gz
sudo nano ~/.profile
export PATH=$PATH:/usr/local/go/bin

Verify install by checking version

go version

 

node.js

update system, install cert and repo, install. there's easier ways but this way got me the correct versions.

sudo apt update
sudo apt install ca-certificates curl gnupg
nodesource repo keyring
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

I chose version 20 because it's LTS and works. newer may work also

NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt update
sudo apt install nodejs

verify by checking version

node --version
npm --version

ensure npm is updated

sudo npm install npm@latest -g

 

typescript

sudo npm install -g typescript
tsc --version

 

the PDS part

follow the official documentation here, it's really well written and easy to follow.

https://github.com/bluesky-social/pds?tab=readme-ov-file#self-hosting-pds

the gist is, use dnschecker.com to verify yourdomain.com, pds.yourdomain.com, and wildcards all resolve to your IP.  then just

wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh
sudo bash installer.sh

the official documentation talks about SMTP a bit, but here's the detail on how i got it working.

 

smtp setup

 a free account on resend is all you need for these purposes.  go to resend.com and do that.

to authenticate your domain there, you have to set a custom MX record, and a few other things. click domains on the left side of resend, and follow their instructions in your DNS.

next, set up an api key, name it whatever PDS, permission = sending access, domain = all domains.  write down the api, you can't see the full thing later. 

finally, configure smtp on the pds. i had to do this directly as root.

echo 'PDS_EMAIL_SMTP_URL=smtps://resend:YOUR_API_KEY@smtp.resend.com:465/' >> /pds/pds.env
echo 'PDS_EMAIL_FROM_ADDRESS=admin@yourdomain.com' >> /pds/pds.env

reboot your PDS. smtp should be working now.

 

goat

if you want to do anything CLI with the PDS, you're going to want to install goat. this is why we installed Go and Typescript earlier.

goat = Go AT protocol cli tool

official docu here https://github.com/bluesky-social/indigo/tree/main/cmd/goat

the manual install way is what worked for me -

git clone https://github.com/bluesky-social/indigo
go build ./cmd/goat
sudo cp goat /usr/local/bin

verify install by opening help

goat --help

 the full documentation is in the goat github.  it's quite useful!

so, at this point, you should have a PDS up and running, with goat installed.  you can now create your user account and verify the email.  the email part took me a lot of fiddling.  here's a few notes on that -

hope this was helpful to someone, enjoy

@28tauri.net