Bluesky PDS

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Bluesky PDS. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Leave the root volume at the default size or larger. The image automatically adds a separate 20 GiB data volume for the account databases and blobstore.

Under Network settings, select your VPC and subnet. Create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks that will reach the server.

Select Launch instance. First-boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Run the following command to launch an instance from the SecureAnyCloud Bluesky PDS Marketplace AMI into an existing subnet and security group.

Replace <ami-id> with the AMI ID shown on the Marketplace listing and <key-name> with your EC2 key pair name. Replace <subnet-id> with your subnet ID and <security-group-id> with a security group that opens ports 22, 80 and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=bluesky-pds-01}]'

On success, the command prints a JSON document. Note the instance ID. Once the instance is running, retrieve its public address with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect over SSH with the key pair you selected and the public IP address from Step 2. The SSH login user depends on the operating system of the AMI variant you launched. For Bluesky PDS on Ubuntu 24.04, the login user is ubuntu:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

First boot generates the per-instance admin password and writes it to a root-only file. Read it with:

sudo cat /root/bluesky-pds-credentials.txt

The file records PDS_HOSTNAME (initially the instance's own AWS address) and PDS_ADMIN_PASSWORD. The JWT signing secret and the secp256k1 PLC rotation key are also generated per instance. They live in /pds/pds.env (mode 0600).

Admin XRPC calls authenticate as the user admin with PDS_ADMIN_PASSWORD, using HTTP Basic auth.

The PDS answers a health endpoint and a server-description endpoint through nginx on port 80. Check the health endpoint, which returns the running server version:

curl -s http://127.0.0.1/xrpc/_health

The response is a JSON version string like this:

{"version":"0.4.5009"}

Next, describe the server. The response reports the server DID, the user-handle domains it accepts, and whether an invite code is required to create an account:

curl -s http://127.0.0.1/xrpc/com.atproto.server.describeServer | jq .

On a freshly launched instance, before you configure your own domain, the response looks like this. The server DID and the available user domain are derived from the instance's own AWS address:

{ "did": "did:web:ec2-203-0-113-10.compute-1.amazonaws.com", "availableUserDomains": [ ".ec2-203-0-113-10.compute-1.amazonaws.com" ], "inviteCodeRequired": true, "links": {}, "contact": {} }

From outside the instance, substitute your instance's public IP or DNS name for 127.0.0.1. For example, run curl -s http://<public-ip>/xrpc/_health.

The Docker engine, the reverse proxy and the PDS run under systemd. The PDS itself runs as a Docker container bound to the loopback interface. Confirm that all four are active:

systemctl is-active docker nginx bluesky-pds bluesky-pds-firstboot

All four report active. Next, inspect the running container. It is published only on 127.0.0.1:3000, so it is never directly exposed to the network. nginx is the only public entry point:

sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'

NAMES IMAGE STATUS PORTS bluesky-pds 1fa8bbceabb6 Up About a minute 127.0.0.1:3000->3000/tcp

nginx also serves an unauthenticated static health endpoint at /healthz, which returns ok. Use it for load balancer and uptime checks.

Account creation is invite-gated by default (inviteCodeRequired is true). The admin API mints invite codes, and it authenticates as admin with the per-instance password. This block reads the password from the credentials file and calls com.atproto.server.createInviteCode:

PW=$(sudo grep '^PDS_ADMIN_PASSWORD=' /root/bluesky-pds-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" -X POST http://127.0.0.1/xrpc/com.atproto.server.createInviteCode \
  -H 'Content-Type: application/json' -d '{"useCount":1}' | jq .

The server returns a single-use invite code:

{ "code": "ec2-203-0-113-10-compute-1-amazonaws-com-tiiwk-jaxlk" }

A wrong admin password is rejected with HTTP 401. To register a new account on your server, hand an invite code to a client or use it with com.atproto.server.createAccount.

To join the wider Bluesky network, the server needs a real public DNS hostname rather than the instance's AWS address, because handles and DIDs are derived from it. The image ships domain-free, so you can set this once you have DNS in place.

• Create two DNS records pointing at the instance's public IP. The first is an A record for your chosen hostname, for example social.example.com. The second is a wildcard A record (*.social.example.com), so user handles like alice.social.example.com resolve. You need the wildcard only if you want handles under your domain.
• Set the hostname in the server's environment file. Edit /pds/pds.env and change the PDS_HOSTNAME line to your domain:

sudo sed -i 's/^PDS_HOSTNAME=.*/PDS_HOSTNAME=your-pds-host.your-domain.example/' /pds/pds.env

• Restart the server so it picks up the new hostname:

sudo systemctl restart bluesky-pds

Re-run the describeServer check from Step 4 and confirm that the did and availableUserDomains now reflect your domain.

Changing PDS_HOSTNAME after accounts exist is disruptive, so set your final domain before onboarding users.

In this image, the server speaks HTTP on port 80. The wider atproto network and clients expect HTTPS on port 443. Terminate TLS in front of the instance using either of these approaches:

• AWS Application Load Balancer (recommended). Create an ALB with an ACM certificate for your domain, an HTTPS:443 listener, and a target group forwarding to the instance on port 80. Point your DNS records at the ALB instead of the instance. This keeps certificate renewal fully managed.
• Your own certificate on the instance. Obtain a certificate for your domain and add a listen 443 ssl; server block to the nginx site at /etc/nginx/sites-available/sac-bluesky-pds. Then reload nginx. If you use a tool like certbot, keep the port 80 server block for the ACME HTTP-01 challenge.

Whichever you choose, make sure the security group allows inbound 443 from your users and that clients reach the server over https://your-domain.

With an invite code in hand, you can register accounts. atproto clients, including the Bluesky app pointed at a custom PDS, walk a user through account creation. The user supplies the invite code and a handle under one of the server's availableUserDomains.

Programmatically, com.atproto.server.createAccount takes an email, handle, password and inviteCode. Account creation publishes a DID to the public PLC directory, so create accounts against your final federated hostname (Step 7), not the temporary AWS address.

The admin API (Basic auth as admin) also exposes server-management endpoints under com.atproto.admin. Examples are disabling invite codes for an account and taking moderation actions. Keep the admin password secret, because anyone with it controls the server.

All durable state lives on the dedicated EBS data volume mounted at /pds. That state is the account and actor SQLite databases, the repository data and the blobstore under /pds/blocks. The operating system, the Docker engine and the pinned container image live on the root volume.

• Snapshots. Take regular EBS snapshots of the /pds data volume, for example with Amazon Data Lifecycle Manager. You can then restore accounts and blobs after a failure.
• Encryption at rest. Enable EBS encryption on the data volume in the AWS console to encrypt the databases and blobs at rest.
• Resizing. When storage runs low, grow the /pds volume in the EC2 console and extend the filesystem with sudo resize2fs $(findmnt -no SOURCE /pds).
• Updates. The container is pinned to a fixed image digest, so it never changes unexpectedly. To move to a newer PDS release, pull the new image and update the image: line in /pds/compose.yaml. Then run sudo systemctl restart bluesky-pds.
• Restart. sudo systemctl restart bluesky-pds recreates the container from the compose file. sudo systemctl restart nginx reloads the proxy.