Do It Yourself: Cloudflare #

Although we think that Aviary is the best way to manage ATProtocol DNS records for most people, we understand that some people may want to manage their own DNS records.

This guide walks you through the process of manually configuring DNS records in Cloudflare to change your handle to a domain or subdomain.

This guide makes some general assumptions:

• You are familiar with DNS and how it works.
• You are somewhat familiar with Cloudflare and how it works.
• You have registered a domaion and it is configured within Cloudflare.

If you are not familiar with these concepts, we recommend that you use Aviary to manage your DNS records. See the Quick-Start guide for more information.

This guide is going to be using the domain dads.lol as an example. You should replace this with your own domain when following the guide.

Step 1: Review Your Cloudflare Account #

Before you start, log into Cloudflare and review the domains associated with your account.

Step 2: Find Your DID #

When you create an ATProtocol account, you are assigned a DID. A DID is a unique identifier that is used to identify your account on the ATProtocol networkd.

More information about DIDs can be found in the ATProto Glossary.

To get your DID, you can use the Aviary Checkup tool found at https://aviary.domains/checkup.

1. On the checkup page, enter your current “Handle” into the form and submit the form.

2. Review the results and find the “DID” value in the first section named “DID Resolution Results”.

3. Copy the “DID” value to your clipboard. You want the entire string, including the “did:plc:” prefix. An example is did:plc:cbkjy5n7bk3ax2wplmtjofq3.

Step 3: Create DNS Records #

Next we’ll create the special DNS record that is used to point requests for your handle to the DID.

More information about handle resolution can be found on the ATProtocol Handle Spec page.

The tl;dr is that you need to create a TXT record for your handle with content that references the DID from above. The format of the record is _atproto.YOURHANDLE.dads.lol with the content did=DID.

1. In the Cloudflare dashboard for the domain, open the records page from the left menu.

2. Click the “Add Record” button to create a new DNS record.

3. In the “Type” dropdown, select “TXT”.

4. In the “Name” field, enter _atproto.YOURHANDLE. You should replace YOURHANDLE with your handle.

5. In the “Content” field, enter did=DID. You should replace DID with the DID from above.

6. Click the “Save” button to save the record.

You should now see your new record in the list of records for the domain.

Variation 1: Bare Domains #

If you are using a “bare domain” (e.g. dads.lol instead of nick.dads.lol), you should create a TXT record with the name _atproto and the content did=DID.

Step 4: Verify DNS Records #

Cloudflare can sometimes take a minute for everything to propogate. Before we proceed with the next step, we should wait for the DNS records to propogate.

Back on the Aviary Checkup Tool, enter the new handle that you want to verify.

Not Ready Yet #

If the checkup tool has empty results in the DID Resolution Results or Handle Resolution Results sections or if the DNS Status section says No DIDs were found. for any Google, Cloudflare, or QuadNine, then the DNS records have not propogated yet.

Ready #

After a few minutes have passed, retry. Eventually you’ll see results that look like this:

The two important sections are Handle Resolution Results and DNS Status.

The Handle Resolution Results section should show both the current (old) handle and the new handle that you want to move two. The reason both are shown is because the DNS records points to your DID, and your DID references your old handle still.

The DNS Status section should show that the DNS records are ready for Google, Cloudflare, and QuadNine. If the DNS records are not ready for any of the providers, then you should wait a few more minutes and try again.

Step 5: Change Your Handle #

The next step is to change your handle with an API call to your PDS to make it official. You can do this by logging into the Bluesky App View at bsky.app.

1. Go to the Settings page from the left menu.

2. Navigate to the Change Handle link.

3. In the form that appears, click on I have my own domain link.

4. In the form that appears, enter the handle that you created the DNS record for.

5. Verify that the expected DNS record matches the one that you created in step 3.

6. Click the Verify DNS Record button to continue.

7. IF your PDS is able to verify the DNS record independantly, then you will see a success message. Click the Change Handle button to continue.

Step 6: Verify Your Handle #

The final step is to verify that your handle has been changed. This is just a victory lap to make sure that everything is working as expected.

Go back to the Aviary Checkup Tool and enter the new handle that you changed to.

You should see results that look like this:

• The DID Resolution Results section should show the DID that you created the DNS record for.
• The Handle Resolution Results section should show only one record: the new handle that you changed to.
• The DNS Status section should show that the DNS records are ready for Google, Cloudflare, and QuadNine.

Step 7: Done #

You’re done! You’ve successfully changed your handle to a domain or subdomain using Cloudflare.

The process isn’t exceptionally complicated, but there are a lot of places where a typo here or a miss-click there can cause things to go wrong. It gets even more complicated and risky if you’re helping other people and organizations with handles off of your domain. That’s where Aviary comes in.

Whether your the only person using a bare domain, your working with a team of people all using a domain for handles, or you want to open it to your community or the public, Aviary can make it easier and safer to manage your DNS records.

If you’ve followed these instructions, or you’ve already created a handful of records, Aviary can import all of your existing records so you don’t loose anything. There’s no sunk-cost, just smooth sailing going forward. The Checkup tool is also a great way to help your people diagnose issues and resolve problems quickly.