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 hosting a Bluesky PDS.

Head over to the ATProto Touchers Discord to chat with other folks hosting instances and get important updates about the PDS distribution!

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 atproto, is a protocol for large-scale distributed social applications.

Please visit the AT Protocol docs for additional information.

Where is the code?

What is the current status of federation?

The AT Protocol network is open to federation!

✅ Federated domain handles (e.g. @nytimes.com)

✅ Federated feed generators (custom algorithms)

✅ Federated relays (event firehose)

✅ Federated app views (API service)

✅ Federated data (PDS hosting)

✅ Federated moderation (labeling)

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.

Deploying a PDS onto a VPS

This README provides instructions for deploying a PDS using our install script onto a Virtual Private Server. Digital Ocean and Vultr are two popular choices for VPS hosting.

Ensure that you can ssh to your server and have root access.

Server Requirements

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

Server Recommendations | | | | ---------------- | ------------ | | Operating System | Ubuntu 24.04 | | Memory (RAM) | 1 GB | | CPU Cores | 1 | | Storage | 20 GB SSD | | Architectures | amd64, arm64 | | Number of users | 1-20 |

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 cloud firewall for HTTP and HTTPS

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

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

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

Note: there is no need to set up TLS or redirect requests from port 80 to 443 because the Caddy web server, included in the Docker compose file, will handle this for you.

Configure DNS for your domain

From your DNS provider's control panel, set up a domain with records pointing to your server.

| Name | Type | Value | TTL | | --------------- | ---- | ------------- | --- | | example.com | A | 12.34.56.78 | 600 | | *.example.com | A | 12.34.56.78 | 600 |

Note:

Replace example.com with your domain name.
Replace 12.34.56.78 with your server's IP address.
Some providers may use the @ symbol to represent the root of your domain.
The wildcard record is required when allowing users to create new accounts on your PDS.
The TTL can be anything but 600 (10 minutes) is reasonable

Check that DNS is working as expected

Use a service like DNS Checker to verify that you can resolve domain names.

Examples to check (record type A):

example.com
random.example.com
test123.example.com

These should all return your server's public IP.

Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13

Note that this script assumes a relatively "fresh" VPS that is not also concurrently hosting a web server or anything else on port 80/443. If you intend to run a PDS alongside an existing webserver on the same VPS, you will not want to use this install script.

On your server, download the install script using curl:

curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh > installer.sh

And then run the installer using bash. You will need sudo permissions to continue:

sudo bash installer.sh

The install script is interactive and will prompt for input during the install process. You will need to provide your public DNS address, an admin email address (which does not need to be from the same domain), and be prompted to create a PDS user account with its own email address and handle. If you plan to reuse an existing AT handle, you can skip user account creation, though if it is your first time deploying a PDS you may want to create an account using your domain like account.your-domain.net for testing purposes.

Upon completion of a successful installation, you'll receive output similar to the following:

========================================================================
PDS installation successful!
------------------------------------------------------------------------

Check service status      : sudo systemctl status pds
Watch service logs        : sudo docker logs -f pds
Backup service data       : /pds
PDS Admin command         : pdsadmin

Required Firewall Ports
------------------------------------------------------------------------
Service                Direction  Port   Protocol  Source
-------                ---------  ----   --------  ----------------------
HTTP TLS verification  Inbound    80     TCP       Any
HTTP Control Panel     Inbound    443    TCP       Any

Required DNS entries
------------------------------------------------------------------------
Name                         Type       Value
-------                      ---------  ---------------
your-domain.net              A          your-ip-address
*.your-domain.net            A          your-ip-address

Detected public IP of this server: your-ip-address

To see pdsadmin commands, run "pdsadmin help"

========================================================================

And, following account creation:

Account created successfully!
-----------------------------
Handle   : handle.your-domain.net
DID      : did:plc:your-did
Password : your-password
-----------------------------
Save this password, it will not be displayed again.

Verifying that your PDS is online and accessible

[!TIP] The most common problems with getting PDS content consumed in the live network usually result from users trying to port the provided Caddy configuration to Nginx, Apache, or other reverse proxies. Getting TLS certificates, WebSockets, and virtual server names provisioned can be challenging. We are not currently providing tech support for other configurations.

After installation, your PDS should be live and accessible on the web. You can check if your server is online and healthy by making a request to https://your-domain.net/xrpc/_health (the healthcheck endpoint). You should see a JSON response with a version, like:

Visit https://your-domain.net/xrpc/_health in your browser. You should see a JSON response with a version, like:

{"version":"0.2.2-beta.2"}

You'll also need to check that WebSockets are working, for the rest of the network to pick up content from your PDS. You can test by installing a tool like wsdump and running a command like:

wsdump "wss://example.com/xrpc/com.atproto.sync.subscribeRepos?cursor=0"

Note that there will be no events output on the WebSocket until they are created in the PDS, so the above command may continue to run with no output immediately post-installation.

goat CLI

The PDS image includes goat, our command line tool for performing admin functions. goat can be used locally with a --pds-host parameter or within the container installed by this script.

Creating an account

You can run the goat command included in this container with docker exec pds goat.

Use goat pds admin account create to create an account

Pds

Install / Use

README

PDS

Table of Contents

FAQ