Add a custom domain to your portal

How to serve your project's portal and articles at a domain you own, such as example.com or blog.example.com, instead of its papera.dev address.

Before you begin

A custom domain comes with the Pro and Ultimate plans. You also need access to your domain's DNS settings, at the registrar or DNS provider where you manage the domain.

Open the project's Settings → Address, and press the edit button beside Custom domain. The setup walks you through five steps and shows the exact records to create. Keep it open while you work in your DNS provider. If you close it, it reopens on the step you left, with your choice and the name you typed.

Choosing the address

The setup's first step, Choose your address, asks which kind of domain you want:

• Root domain, such as example.com, which brings www.example.com with it. The root serves your pages, and www.example.com sends every reader on to the same page on the root, so readers reach you whichever way they type the address. Use it when this portal is your main site. It takes an A record for the root and a CNAME record for www, and it replaces any site example.com hosts now.
• Subdomain, a name of your own under your domain, such as blog.example.com or docs.example.com. It takes one CNAME record, and your root domain keeps its own site. Use it when example.com already hosts your site. A www name comes with its root domain, so to serve at www.example.com, choose Root domain.

Nothing is chosen for you, and neither kind is the better default: your own site on the root domain decides it. Pick one, and the setup moves on to the next step. You can open any step you have reached again by clicking its title.

Entering the domain

The step Enter your domain asks for the name. Enter it and press Continue to claim it. If the name you enter is of the other kind, the setup says so and names the choice that fits it: press the Back arrow at the top of the setup to change the kind. Which names count as root domains follows the public list of domain endings, so example.co.uk is a root domain, just as example.com is.

For a root domain, enter the root only, such as example.com. The setup shows the www name that comes with it, and one ownership record proves both.

A project holds one custom domain at a time.

Adding the ownership record

The step Add the ownership record shows a TXT record that proves the domain is yours. In your DNS provider, create a record with these fields:

• Type: TXT
• Host or Name: the host the setup shows
• Value or Target: the value the setup shows

Most providers add your domain to the host on their own, so the setup shows the host without it, for example _papera-challenge or _papera-challenge.blog, and @ for the domain itself. If your provider asks for the full name instead, the setup shows it under the host. Every value has a copy button, so nothing has to be retyped. Press Continue to go on.

Adding the pointing record

The step Point the domain here shows the record that sends visitors to your project. It depends on the kind of domain you chose.

For a Subdomain, create one record:

• Type: CNAME
• Name or Host: your name, such as blog or news
• Value or Target: edge.papera.dev

For a Root domain, create two records. The first sends the root to your project:

• Type: A
• Name or Host: your domain, often written as @
• Value or Target: the A record value the setup shows

If your DNS provider offers ALIAS, ANAME or flattened CNAME records, one for your root domain pointing at edge.papera.dev works in place of the A record.

The second sends the www name to Papera, which redirects it to the root:

• Type: CNAME
• Name or Host: www
• Value or Target: edge.papera.dev

Remove any AAAA record for the same names, and turn off any proxy in front of the domain. Press Continue to go on.

Verifying

The step Verify reports three results:

• Ownership record found: the TXT record holds this project's value.
• Domain points at this project: the pointing record leads to Papera.
• Answers over a secure connection: the domain has a trusted certificate and answers for this project.

When all three pass, the domain is live. Every address of the project then names it, and the papera.dev address keeps serving the same pages.

For a root domain, the step also shows whether the www name points at this project. It is checked on its own and never holds the root back: the root goes live without it, and www redirects to the root once its record is in place. The Custom domain row in Settings shows the www name beneath the root, with whether its record is still to add.

Papera checks on its own after you claim the domain: every 5 minutes for the first hour, every 30 minutes for the rest of the first day, then every 6 hours until a week has passed. Once both records are found, it checks the secure connection every 15 minutes for two hours, every hour for the rest of that day, then every 6 hours for a week. A live domain is checked every 6 hours for as long as it stays live.

Until the domain is live, press Check records on this step to check at once, whether or not an automatic check is due. Once the automatic checks stop, that button is the only check left. On a live domain, Continue closes the setup, and Check again checks at once.

Troubleshooting

The check says a record sits at a doubled name, such as _papera-challenge.example.com.example.com. Your provider added your domain to a host that already ended with it. Edit the record and set its host to the one the message names.

The domain answers for something other than this project, or resolves to another address. A proxy in front of the domain is the usual cause. Turn it off for both records.

Cloudflare: set each record to DNS only, the grey cloud. Cloudflare proxies new records by default, and a proxied record fails the check.

The check reports an AAAA record. Your domain has an IPv6 address as well, and Papera serves custom domains over IPv4 only. Delete the AAAA record for that name.

The check reports the www name as not pointed yet. The root domain still goes live, but readers who type www reach nothing until the record is in place. Create the CNAME record for www to edge.papera.dev, delete any other A, AAAA or CNAME record for www, and turn off any proxy for it. Some registrars add a www record of their own, or forward www somewhere else, so remove that too. Then wait a few minutes and check again.

A root domain keeps resolving to another address after you added the A record. Many registrars park a new domain with their own A record or a forwarding rule. The check names each address beside Papera's, on the domain or on its www name:

example.com also points at 34.120.5.9. Delete that A record. DNS caches answers, so a record you just changed can take a while to clear.

Delete every A record the message names, and turn off any parking or forwarding page.

Both records are found, but the secure connection never passes. The check reads the CAA records of your domain, then of each parent domain, and stops at the first one that has any. When those records leave out Let's Encrypt, the authority that issues the certificate, the check names the domain that holds them:

The CAA records on example.com leave out Let's Encrypt, so this domain can't get its certificate. Add a CAA record on example.com with the value 0 issue "letsencrypt.org". DNS caches answers, so a record you just changed can take a while to clear.

Add this CAA record on the domain the message names:

0 issue "letsencrypt.org"

A record you just added is reported as missing. DNS answers are cached for a while, so a new or changed record can take a few minutes to arrive, and sometimes longer. Wait, then press Check records again.

The secure connection is still pending. The certificate is issued once the records are in place, which can take a few minutes. Papera keeps checking on its own, so you can close the setup with Cancel and come back.

Removing or changing the domain

To give the domain up, open the setup and press Remove domain. The domain stops belonging to the project at once, and the project's papera.dev address keeps serving its pages. Removing a root domain removes its www name with it.

A project holds one custom domain, so to change it, remove the current domain first, then claim the new one. You can delete the old DNS records afterwards.