Skip to content
/ pds Public
forked from bluesky-social/pds

Bluesky PDS (Personal Data Server) container image, compose file, and documentation

License

Notifications You must be signed in to change notification settings

TampaDevs/pds

 
 

Repository files navigation

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.

Head over to the AT Protocol PDS Admins Discord to get started!

Table of Contents

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?

As of Feb, 2024, the AT Protocol PDS (Personal Data Server) is now open to federation for self-hosters!

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

✅ Federated feed generators (custom algorithms)

✅ Federated relays (event firehose)

✅ Federated app views (API service)

✅ Federated data for self-hosters (PDS hosting)

✅ Federated moderation (labeling)

🚧 Federated data for large service providers (coming soon)

What should I know about running a PDS in the developer sandbox?

Developers may now run self-hosted PDS hosts on the production network!

Though it is still recommended to run experiments in the developer sandbox network.

Read the SANDBOX.md for an overview of the sandbox network.

Self-hosting PDS

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

Important

Initially to join the network you'll need to join the AT Protocol PDS Admins Discord and register the hostname of your PDS. We recommend doing so before bringing your PDS online. In the future, this registration check will not be required.

Preparation for self-hosting PDS

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

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 22.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.

Installer on Ubuntu 20.04/22.04 and Debian 11/12

On your server via ssh, download the installer script using wget:

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

or download it using curl:

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

And then run the installer using bash:

sudo bash installer.sh

Verifying that your PDS is online and accessible

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

You can visit https://example.com/xrpc/_health in your browser. You should see a JSON response with a version.

For example:

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

Creating an account using pdsadmin

Using ssh on your server, use pdsadmin to create an account if you haven't already.

sudo pdsadmin account create

Creating an account using an invite code

Using ssh on your server, use pdsadmin to create an invite code.

sudo pdsadmin create-invite-code

When creating an account using the app, enter this invite code.

Using the Bluesky app with your PDS

You can use the Bluesky app to connect to your PDS.

  1. Get the Bluesky app
  2. Enter the URL of your PDS (e.g. https://example.com/)

Note: because the subdomain TLS certificate is created on-demand, it may take 10-30s for your handle to be accessible. If you aren't seeing your first post/profile, wait 30s and try to make another post.

Updating your PDS

It is recommended that you keep your PDS up to date with new versions, otherwise things may break. You can use the pdsadmin tool to update your PDS.

sudo pdsadmin update

License

This project is dual-licensed under MIT and Apache 2.0 terms:

Downstream projects and end users may choose either license individually, or both together, at their discretion. The motivation for this dual-licensing is the additional software patent assurance provided by Apache 2.0.

About

Bluesky PDS (Personal Data Server) container image, compose file, and documentation

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Shell 89.4%
  • JavaScript 7.6%
  • Dockerfile 3.0%