Docs

Domain and DNS

Choose your domain and point it at your server before you install. One A record is all it takes.

ClientOS runs on one domain of your own. Before you install, point that domain at your server with a single DNS record. Do it first: DNS can take a few minutes to spread, and the installer checks the record before it downloads anything. With the record already in place, installation is a straight run from start to finish.

One domain, everything on it#

You choose one address, for example clients.youragency.com. Your clients, your team, the API and your files all live on it:

Address	What it is
`https://clients.youragency.com`	Your client portal. Clients sign in, buy, pay and follow their orders here. Your public service pages, forms and pay links live here too.
`https://clients.youragency.com/admin`	The admin, where your team works.
`https://clients.youragency.com/v1`	The API, which payment gateways and email webhooks call.

Everybody signs in on the same page. Your team lands in the admin and your clients land in their portal. HTTPS certificates are issued and renewed for you, so there's nothing to buy or upload.

Choosing your domain#

A subdomain is the usual choice, such as clients.youragency.com, portal.youragency.com or app.youragency.com. Your main website stays where it is, and ClientOS gets an address of its own beside it.

A whole domain works too, such as youragencyportal.com, if you'd rather give ClientOS a domain of its own.

The domain must be:

A real, public domain you can add DNS records to. Not an IP address, and not a local name such as localhost or myserver.lan.
Not already used by a website. Pointing it at your ClientOS server takes it over.
The one you mean to keep. Your license is bound to it. You can move to another domain later from the admin, but a key can change domain three times in its life. See Moving to another domain.

ClientOS installs only on a server your domain reaches over the internet. Before anything is downloaded, Vibemonk's license server checks, from outside, that your domain answers on your server. A laptop, a home network or a domain that isn't pointed yet can't install it.

1. Find your server's IP address#

Your hosting provider shows it on the server's overview page, labelled Public IPv4 or IP address. It looks like 203.0.113.5. You can also print it on the server:

Terminal

curl -4 ifconfig.me

2. Add an A record#

Sign in where you manage your domain's DNS. That's usually where you bought the domain (Namecheap, GoDaddy, Hostinger, Porkbun), or Cloudflare if you moved your DNS there. Add one record:

DNS records

Type   Name      Value          TTL
A      clients   203.0.113.5    Auto (or 300)

What goes in Name depends on the address you chose:

Your ClientOS address	Name	Value
`clients.youragency.com`	`clients`	Your server's IP
`portal.youragency.com`	`portal`	Your server's IP
`youragencyportal.com` (a whole domain)	`@`	Your server's IP

Some providers want the full name (clients.youragency.com) in the Name field instead of just clients. If yours does, it says so, or it adds the domain for you as you type.

Provider notes#

Provider	Where to add it
Cloudflare	Your domain, then DNS → Records → Add record. Set Proxy status to DNS only (grey cloud). See below.
Namecheap	Domain List → Manage → Advanced DNS → Add new record → A Record. Host is `clients`.
GoDaddy	My Products → your domain → DNS → Add New Record → A. Name is `clients`.
Hostinger	Domains → your domain → DNS / Nameservers → Add record, type A.
AWS Route 53	Hosted zones → your domain → Create record, type A, record name `clients`.
DigitalOcean	Networking → Domains → your domain, type A, hostname `clients`.

On Cloudflare#

Set the record to DNS only (grey cloud) while you install. Let's Encrypt has to reach your server directly to issue the first HTTPS certificate, and Cloudflare's proxy (orange cloud) gets in the way. You can turn the proxy on once ClientOS is running; see Cloudflare's proxy.

Remove an old AAAA record#

If the name already has an AAAA (IPv6) record pointing somewhere else, delete it, unless it's your server's own IPv6 address. Let's Encrypt tries IPv6 first, and an AAAA record that leads elsewhere stops the certificate. The installer warns you if it sees one.

3. Check that it has spread#

A new record usually appears within a few minutes, and occasionally takes up to an hour. Check it from any computer:

Terminal

# macOS or Linux
dig +short clients.youragency.com @1.1.1.1

# Windows
nslookup clients.youragency.com 1.1.1.1

When it prints your server's IP address, you're ready to install. Online checkers such as dnschecker.org show how far it has spread around the world.

You don't have to wait for it to be perfect: the installer's browser page checks the record by itself every few seconds and tells you the moment it's right.

What the installer checks#

When you connect your domain during installation, ClientOS doesn't just look the record up. It:

looks your domain up on public DNS (Cloudflare, Google and Quad9), not the server's own resolver, which can remember an old "not found";
sends a request to your domain and checks that it arrives at this server, so a record pointing at the wrong machine never passes;
tells you exactly what's wrong when it doesn't pass, for example "clients.youragency.com points at 198.51.100.7, not this server. Change its A record to 203.0.113.5."

DNS you'll add later#

The A record is the only one you need to install. After setup, when you connect email, your email provider gives you a few more records (SPF and DKIM) so your messages reach inboxes instead of spam. See First run.

Troubleshooting#

Problem	What to do
`has no A record yet`	The record isn't visible on public DNS yet. Check the Name field and wait a few minutes.
`points at …, not this server`	The record has the wrong IP. Change its value to your server's IP.
`reaches this server through …, which looks like a proxy`	Cloudflare's proxy is on. Set the record to DNS only until ClientOS is running.
`also has an IPv6 (AAAA) record`	Delete the AAAA record, unless it's your server's own IPv6 address.
`is not a domain anybody owns`	You typed a domain suffix such as `co.uk` on its own. Enter your full address.
`Use a domain name, not an IP address`	ClientOS needs a domain for HTTPS and for your license.
The record is right but the check still fails	Your provider's firewall is blocking port 80. Allow ports 80 and 443 there. See Ports 80 and 443.

Next: Installation#

Your domain points at your server. Continue with Installation.