How to Migrate a Bluesky Account to a Self-Hosted PDS

You want to move your Bluesky account from the official Bluesky Social PDS to your own self-hosted Personal Data Server. This lets you control your data, choose your moderation policies, and avoid relying on Bluesky’s infrastructure. The migration process involves exporting your data, setting up a PDS, and updating your account handle. This article explains the prerequisite server setup and provides step-by-step instructions for the migration.

Understanding the Bluesky PDS Architecture

Bluesky uses the AT Protocol, which separates account data from the social graph. Each user’s data lives on a Personal Data Server. The official Bluesky Social PDS is the default for most users. When you self-host, you run the same server software on your own machine. The protocol allows you to move your identity and data to a different PDS without losing your followers or posts. You must have a domain name and a server with Docker installed before you start.

What a Self-Hosted PDS Provides

Running your own PDS gives you full control over your data storage, backup frequency, and server location. You can also configure custom moderation feeds and blocklists. The server software is open source and maintained by Bluesky. You need basic Linux administration skills to manage updates, security patches, and backups.

Prerequisites Checklist

Before migrating, prepare these items:

• A Linux server with at least 2 GB RAM and 20 GB disk space
• Docker and Docker Compose installed
• A registered domain name with DNS management access
• Port 80 and 443 open on your firewall
• A registered email address for SSL certificate notifications

Steps to Migrate Your Bluesky Account to a Self-Hosted PDS

Step 1: Export Your Bluesky Account Data

1. Open Bluesky settings
   Click your profile picture in the top-right corner and select Settings from the dropdown menu.
2. Navigate to Account
   In the left sidebar, click Account. Scroll down to the Data section.
3. Start the export
   Click Export Data. A ZIP file containing your posts, likes, follows, lists, and mute blocks downloads to your computer. Keep this file safe; you will not need it for the migration itself, but it serves as a backup.

Step 2: Deploy the PDS on Your Server

1. Connect to your server
   SSH into your Linux server. Update the package list: sudo apt update && sudo apt upgrade -y.
2. Install Docker and Docker Compose
   Run the official Docker installation script: curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh. Then install Docker Compose: sudo apt install docker-compose-plugin.
3. Create the PDS directory
   Make a folder for the PDS: mkdir ~/pds && cd ~/pds.
4. Download the PDS configuration template
   Run: wget https://raw.githubusercontent.com/bluesky-social/pds/main/docker-compose.yaml. This downloads a Docker Compose file with default settings.
5. Edit environment variables
   Open the docker-compose.yaml file with a text editor: nano docker-compose.yaml. Set these values:
   PDS_HOSTNAME=yourdomain.com
PDS_JWT_SECRET=generate-a-random-64-char-string
PDS_ADMIN_PASSWORD=your-strong-admin-password
PDS_PLC_ROTATION_KEY=generate-another-random-64-char-string
   Save and exit.
6. Start the PDS
   Run: sudo docker compose up -d. The server pulls the image and starts the container.
7. Verify the server is running
   Check logs: sudo docker compose logs -f. Look for a line saying “Server is running on port 2583”. Press Ctrl+C to exit logs.

Step 3: Configure DNS Records for Your Domain

1. Add a TXT record for domain verification
   In your DNS provider’s control panel, create a TXT record with the host _atproto and value did=did:plc:your-PLC-identifier. You can find your PLC identifier in the PDS logs after first startup.
2. Add a CNAME record for the PDS
   Create a CNAME record with host pds pointing to your server’s IP address or hostname. This allows Bluesky to locate your PDS.
3. Wait for DNS propagation
   DNS changes can take up to 24 hours. Check propagation using a tool like whatsmydns.net. Proceed only when both records resolve correctly.

Step 4: Change Your Handle to the Custom Domain

1. Open Bluesky settings
   Click your profile picture and select Settings.
2. Go to Account
   Click Account in the left sidebar. Find the Handle section.
3. Enter your custom domain
   Type your full domain name, for example yourdomain.com. Click Save. Bluesky verifies the DNS records. If successful, your handle changes to @yourdomain.com.
4. Test the new handle
   Ask a friend to search for @yourdomain.com in Bluesky. They should see your profile with all your existing posts and followers.

Common Migration Issues and How to Resolve Them

DNS verification fails with “Handle not found”

This usually means the TXT or CNAME record is missing or incorrect. Double-check the host name and value. The TXT record must use the host _atproto exactly, not atproto. Wait at least 30 minutes after updating and try again.

PDS container exits immediately after starting

Check the logs with sudo docker compose logs. Common causes include missing environment variables, incorrect JWT secret format, or port conflicts. Ensure PDS_JWT_SECRET and PDS_PLC_ROTATION_KEY are at least 64 characters long. Change the host port in docker-compose.yaml if port 2583 is already in use.

Old handle still shows after migration

Bluesky caches handles for a few hours. Log out of the app and log back in. If the old handle persists after 24 hours, clear the app cache or reinstall the app. Your data remains intact on the new PDS.

Self-Hosted PDS vs Bluesky Social PDS: Key Differences

Item	Self-Hosted PDS	Bluesky Social PDS
Data Control	Full ownership of all data files	Data stored on Bluesky servers
Server Location	Choose your own data center	Bluesky chooses the location
Moderation	Custom feeds and blocklists	Bluesky default moderation
Maintenance	Manual updates and backups	Automatic updates
Cost	Server hosting fees	Free to use
Uptime Responsibility	You manage server uptime	Bluesky manages uptime

You can now run your own Bluesky PDS with full control over your data. Next, configure automated backups using cron jobs to protect your posts and followers. For advanced users, consider setting up a secondary PDS as a failover using the same domain with different DNS records.