PDS#

Welcome to the repository for the official Bluesky PDS (Personal Data Server). This repository includes container images and documentation designed to assist technical people with self-hosting a Bluesky PDS.

FAQ#

What is Bluesky?#

Bluesky is a social media application built on AT Protocol.

Please visit the Bluesky website for more information.

What is AT Protocol?#

The Authenticated Transfer Protocol, aka ATP, is a protocol for large-scale distributed social applications.

Please visit the AT Protocol docs for additional information.

Where is the code?#

• Canonical TypeScript code
• Experimental Go code

Self-hosting a PDS#

Self-hosting a Bluesky PDS means running your own Personal Data Server that is capable of federating with the wider Bluesky social network.

Launch your server#

Launch a server on any cloud provider, Digital Ocean and Vultr are two popular choices.

Server Requirements

• Public IPv4 address
• Public DNS name
• Public internet access permitted on port 80/tcp and 443/tcp

Server Recommendations

Install your server#

Install your Ubuntu 22.04 server, and then ensure that you can ssh to it.

NOTE: It is a good security practice to restrict inbound ssh access (port 22/tcp) to your own computer's public IP address. You can check your current public IP address using ifconfig.me.

Open your firewall#

One of the most common sources of misconfiguration is not opening firewall ports correctly. Please be sure to double check this step.

It may be helpful to use a remote port scanning service to verify that access is permitted. Once your server is fully configured, this service should display the ports as open.

Open ports on your cloud provider's firewall#

In your cloud provider's console, the following ports should be open to access from the public internet.

• 80/tcp (Used only for TLS certification verification)
• 443/tcp (Used for all application requests)

Open ports on your Linux firewall#

If your server is running a Linux firewall managed with ufw, you will also need to open these same ports on the server itself.

$ sudo ufw allow 80/tcp
$ sudo ufw allow 443/tcp

Install Docker#

To install Docker CE (Community Edition) on Ubuntu 22.04, use the the following instructions. For other operating systems you may reference the official Docker install guides.

NOTE: All of the following commands should be run on your server via ssh.

Uninstall old versions#

sudo apt-get remove docker docker-engine docker.io containerd runc

Set up the repository#

sudo apt-get update
sudo apt-get install \
    ca-certificates \
    curl \
    gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine#

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker Engine installation#

sudo docker run hello-world

Set up the PDS directory#

# Create the directory where all PDS data will be stored.
sudo mkdir /data

# Create the required caddy webserver directories.
sudo mkdir --parents /data/caddy/{etc,data}

Start the PDS containers#

Download the Docker compose file#

Download the sqlite-compose.yaml to run your PDS with a local SQLite database.

curl https://raw.githubusercontent.com/bluesky-social/pds/main/sqlite-compose.yaml >compose.yaml

Or, download the postgres-compose.yaml to run your PDS with a remote PostgreSQL database.

curl https://raw.githubusercontent.com/bluesky-social/pds/main/postgres-compose.yaml >compose.yaml

Edit your compose.yaml file#

You will need to customize various settings configured through the PDS environment variables.

Run docker compose#

Run docker compose up to start the three required containers.

docker compose up --wait --detach

You should see output similar to this:

[+] Running 3/3
 ✔ Container watchtower  Healthy  1.1s 
 ✔ Container pds         Healthy  1.1s 
 ✔ Container caddy       Healthy  1.0s

Verify your PDS is online#

You can check if your server is online and healthy by requesting the healthcheck endpoint.

curl https://example.com/xrpc/_health
{"version":"v1.2.3"}

Connecting to your server#

You can use the Bluesky app to connect to your server to create an account.

1. Download the Bluesky app
2. Enter the URL of your PDS (e.g. https://example.com/)
3. Create an account