How domains work

Two companies, two jobs#

Two things happen to a domain, and they do not have to happen at the same company.

• The registrar is where you bought the name. It keeps the name yours and takes the yearly payment.
• The DNS company keeps the address book: which server each name goes to. DNS is that address book.

Often both are the same company. Sometimes they are not, for example when a domain from Namecheap has its address book at OVH or deSEC.

Three ways to set it up#

• One company does both. Connect that company once. LibrePortal reads the records already there, saves a backup in your vault, then adds only what your server needs. Mail, verification records and everything else are left alone. If a name already points somewhere else, LibrePortal asks you first: Keep it or Replace it.

• Another DNS company. You keep the domain where you bought it and use a different company for its address book. LibrePortal asks that company to take the domain, copies your existing records across after you have seen the list, and shows the two name servers to set at the registrar. At OVH, adding a zone for another company's domain is a free order, and LibrePortal asks you to confirm it before it places it. It never places an order that costs money.

• You add the records yourself. Choose Somewhere else. LibrePortal shows each record with copy buttons, and keeps checking every minute until they work. This is the way to use any company the app cannot connect to.

Pointing a domain at a new DNS company#

Name servers are the registrar's list of who answers for your domain. Moving the address book means changing that list at the registrar:

1. Sign in where you bought the domain.
2. Open the domain's name server settings. It may be called Nameservers or DNS servers. In Namecheap: Domain List, Manage, Nameservers, Custom DNS.
3. Choose custom, and paste the names LibrePortal shows, each with a Copy button.
4. Save.

If Namecheap is connected and the domain is registered there, Set them at Namecheap for me does this for you. It saves the old settings in your vault first, and Undo at Namecheap puts them back.

The change can take a few hours, sometimes up to a day. LibrePortal keeps checking and says when it has switched. The install never waits for it, and your server keeps working on its own address in the meantime.

Buying a domain#

If you do not have a domain yet, Buy a new domain lets you pick a company, search a name and see the price for the first year and every year after. Nothing is bought until you press Buy for and the price. By default your name and address are kept private for free, where the ending allows it, and the page says plainly when it does not. OVH is recommended. Namecheap is listed too, with a note first: it only lets apps connect once your account has $50 in it, 20 domains or $50 spent.

What LibrePortal does for you#

• Records. The domain itself, plus a wildcard so every app gets its own address, such as photos.yourname.com.
• Certificates. Secure addresses are set up on the server, and a rule is added to the domain so only Let's Encrypt may issue certificates for it.
• A backup first. The old records are saved in your vault before any change, and every change can be undone from the domain's page.

Connecting a company#

Each company is connected once, and all your servers share it. The app shows these steps before it asks for anything.

Each company has its own page with the steps: Connect OVH, Connect Namecheap and Connect deSEC. In short:

• Namecheap. Create or sign in to your account. Open Profile, Tools, API Access and turn it on. Namecheap only allows this on accounts with at least $50 balance, 20 domains, or $50 spent in the last two years. Add this computer's internet address to the allowed list (the app can show it, with a Copy button), then paste the API key into the app. If your account is not allowed API access, add the records yourself.

• OVH. Choose your region, open OVH's key page and make an application called LibrePortal, paste its key and secret into the app, then press Connect and approve on OVH's own page.

• deSEC. Create a free account, open Token management, create a token, and paste it into the app.

When the registrar cannot be connected#

If the company where you bought the domain cannot be connected to the app, the Connect page offers two ways, each with a checklist where every step ticks itself when the app sees it is done.

Fully managed with deSEC (recommended). Make a free deSEC account, paste a token, confirm the records to copy (the app reads them from public DNS, or from your registrar when it is connected, and Add one adds any it cannot see), then paste deSEC's two name servers at your registrar. The app waits for the switch and checks every minute.

Manage it yourself. The app lists the records your server needs, each with copy buttons and the registrar's menu steps. A row ticks when it resolves correctly.

Continue unlocks when everything is ticked. Finish this later carries on with the setup; the checklist stays open on the server's Domains page and keeps checking, and it survives closing the app.

For trying Namecheap without touching a real domain, the Namecheap connect page has a Use the Namecheap sandbox switch. It needs a separate free account at sandbox.namecheap.com.

See also Domains and HTTPS for how the server uses a domain once it is set up, and DNS for your VPN for names that only work on your private network.