diff --git a/README.md b/README.md index 9a68f1d..d3aa2f9 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,12 @@ Head over to the [ATProto Touchers Discord](https://discord.atprotocol.dev/) to - [What is AT Protocol?](#what-is-at-protocol) - [Where is the code?](#where-is-the-code) - [What is the current status of federation?](#what-is-the-current-status-of-federation) - - [Self-hosting PDS](#self-hosting-pds) - - [Preparation for self-hosting PDS](#preparation-for-self-hosting-pds) + - [Self-hosting a PDS](#self-hosting-a-pds) + - [Deploying a PDS onto a VPS](#deploying-a-pds-onto-a-vps) - [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https) - [Configure DNS for your domain](#configure-dns-for-your-domain) - [Check that DNS is working as expected](#check-that-dns-is-working-as-expected) - - [Installer on Ubuntu 20.04/22.04/24.04 and Debian 11/12](#installer-on-ubuntu-200422042404-and-debian-1112) + - [Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12](#installing-on-ubuntu-200422042404-and-debian-1112) - [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible) - [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin) - [Creating an account using an invite code](#creating-an-account-using-an-invite-code) @@ -56,7 +56,7 @@ Please visit the [AT Protocol docs](https://atproto.com/guides/overview) for add ### What is the current status of federation? -As of Spring 2024, the AT Protocol network is open to federation! +The AT Protocol network is open to federation! ✅ Federated domain handles (e.g. `@nytimes.com`) @@ -70,13 +70,13 @@ As of Spring 2024, the AT Protocol network is open to federation! ✅ Federated moderation (labeling) -## Self-hosting PDS +## 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. -### Preparation for self-hosting PDS +### Deploying a PDS onto a VPS -Launch a server on any cloud provider, [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices. +This README provides instructions for deploying a PDS using our install script onto a Virtual Private Server. [Digital Ocean](https://digitalocean.com/) and [Vultr](https://vultr.com/) are two popular choices for VPS hosting. Ensure that you can ssh to your server and have root access. @@ -106,7 +106,7 @@ In your cloud provider's console, the following ports should be open to inbound * 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. +**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 Dockerfile install method, will handle this for you. ### Configure DNS for your domain @@ -135,34 +135,75 @@ Examples to check (record type `A`): These should all return your server's public IP. -### Installer on Ubuntu 20.04/22.04/24.04 and Debian 11/12 +### Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12 -On your server via ssh, download the installer script using wget: +On your server, download the install script using `curl`: ```bash -wget https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh +curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh > installer.sh ``` -or download it using curl: +And then run the installer using bash: ```bash -curl https://raw.githubusercontent.com/bluesky-social/pds/main/installer.sh >installer.sh +sudo bash installer.sh ``` -And then run the installer using bash: +You will need `sudo` permissions to continue. 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. -```bash -sudo bash installer.sh +You should receive the following output following a successful installation: + +``` +======================================================================== +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 are when folks substitute the provided Caddy configuration for nginx, apache, or similar reverse proxies. Getting TLS certificates, WebSockets, and virtual server names all correct can be tricky. We are not currently providing tech support for other configurations. +> 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. -You can check if your server is online and healthy by requesting the healthcheck endpoint. +After installation, your PDS should be live and web-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, 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"} @@ -174,11 +215,11 @@ You'll also need to check that WebSockets are working, for the rest of the netwo 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 if things are configured successfully. +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. ### Creating an account using pdsadmin -Using ssh on your server, use `pdsadmin` to create an account if you haven't already. +You'll now have access to some additional command line tools on this server. Use `pdsadmin` to create an account if you haven't already: ```bash sudo pdsadmin account create @@ -186,7 +227,7 @@ sudo pdsadmin account create ### Creating an account using an invite code -Using ssh on your server, use `pdsadmin` to create an invite code. +If needed, use `pdsadmin` to create an invite code: ```bash sudo pdsadmin create-invite-code @@ -210,9 +251,9 @@ _Note: because the subdomain TLS certificate is created on-demand, it may take 1 To be able to verify users' email addresses and send other emails, you need to set up an SMTP server. -One way to do this is to use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices. +As an alternative to running your own SMTP server, you can use an email service. [Resend](https://resend.com/) and [SendGrid](https://sendgrid.com/) are two popular choices. -Create an account and API key on an email service, ensure your server allows access on the required ports, and set these variables in `/pds/pds.env` (example with Resend): +Create an account and API key on an email service, ensure your server allows access on the required ports, and then you can add these configuration variables to `/pds/pds.env` on your server (example with Resend): ``` PDS_EMAIL_SMTP_URL=smtps://resend:@smtp.resend.com:465/ @@ -265,7 +306,7 @@ LOG_LEVEL=debug ### 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. +It is recommended that you keep your PDS up to date with new versions. You can use the `pdsadmin` tool to update your PDS. ```bash sudo pdsadmin update -- 2.51.2 From 10630169d1eaf343cc03646c030da66cb043796b Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Wed, 29 Oct 2025 11:55:48 -0700 Subject: [PATCH 2/7] list Debian 13 as supported --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d3aa2f9..59c8e10 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Head over to the [ATProto Touchers Discord](https://discord.atprotocol.dev/) to - [Open your cloud firewall for HTTP and HTTPS](#open-your-cloud-firewall-for-http-and-https) - [Configure DNS for your domain](#configure-dns-for-your-domain) - [Check that DNS is working as expected](#check-that-dns-is-working-as-expected) - - [Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12](#installing-on-ubuntu-200422042404-and-debian-1112) + - [Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13](#installing-on-ubuntu-200422042404-and-debian-111213) - [Verifying that your PDS is online and accessible](#verifying-that-your-pds-is-online-and-accessible) - [Creating an account using pdsadmin](#creating-an-account-using-pdsadmin) - [Creating an account using an invite code](#creating-an-account-using-an-invite-code) @@ -135,7 +135,7 @@ Examples to check (record type `A`): These should all return your server's public IP. -### Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12 +### Installing on Ubuntu 20.04/22.04/24.04 and Debian 11/12/13 On your server, download the install script using `curl`: -- 2.51.2 From 4db6cf8e47addf96c910e35c1c12c67070bf7171 Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Wed, 29 Oct 2025 11:56:56 -0700 Subject: [PATCH 3/7] validate debian 13 in install script --- installer.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/installer.sh b/installer.sh index 6ae77b2..26d4901 100644 --- a/installer.sh +++ b/installer.sh @@ -105,11 +105,14 @@ function main { elif [[ "${DISTRIB_CODENAME}" == "bookworm" ]]; then SUPPORTED_OS="true" echo "* Detected supported distribution Debian 12" + elif [[ "${DISTRIB_CODENAME}" == "trixie" ]]; then + SUPPORTED_OS="true" + echo "* Detected supported distribution Debian 13" fi fi if [[ "${SUPPORTED_OS}" != "true" ]]; then - echo "Sorry, only Ubuntu 20.04, 22.04, 24.04, Debian 11 and Debian 12 are supported by this installer. Exiting..." + echo "Sorry, only Ubuntu 20.04, 22.04, 24.04, and Debian 11, 12, and 13 are supported by this installer. Exiting..." exit 1 fi -- 2.51.2 From 20b15527f95a7ee51c8c18d88d0b2900d6224708 Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Fri, 31 Oct 2025 09:59:06 -0700 Subject: [PATCH 4/7] note expectations of fresh VPS --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 59c8e10..a79a027 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,8 @@ 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`: ```bash -- 2.51.2 From ccb3b5c9de2ca0b48f431c2ea92283a8c9b7bf06 Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Mon, 3 Nov 2025 09:20:16 -0800 Subject: [PATCH 5/7] Update README.md Co-authored-by: Emelia Smith --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a79a027..15e4e33 100644 --- a/README.md +++ b/README.md @@ -203,7 +203,7 @@ Save this password, it will not be displayed again. > [!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 web-accessible. You can check if your server is online and healthy by requesting the healthcheck endpoint. +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: -- 2.51.2 From 857372e8e3d934359cc91a2e1a9044fa632df9c1 Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Mon, 3 Nov 2025 09:20:22 -0800 Subject: [PATCH 6/7] Update README.md Co-authored-by: Emelia Smith --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 15e4e33..912df74 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ sudo bash installer.sh You will need `sudo` permissions to continue. 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. -You should receive the following output following a successful installation: +Upon completion of a successful installation, you'll receive output similar to the following: ``` ======================================================================== -- 2.51.2 From 68d690857e28f02c64cc6e62ded929f5902e1a3f Mon Sep 17 00:00:00 2001 From: Alex Garnett Date: Mon, 3 Nov 2025 09:21:45 -0800 Subject: [PATCH 7/7] feedback cleanups --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 912df74..96d9347 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ In your cloud provider's console, the following ports should be open to inbound * 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 Dockerfile install method, will handle this for you. +**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 @@ -145,13 +145,13 @@ 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: +And then run the installer using `bash`. You will need `sudo` permissions to continue: ```bash sudo bash installer.sh ``` -You will need `sudo` permissions to continue. 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. +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: