Custom domains#

With a license key, an agent can show its Hosted Chat on a domain of its own, such as help.yourshop.com. The agent's owner adds the domain on the agent's Deploy page. See Custom domain.

This page is for the person who runs the Chatvia server. With the installer's HTTPS proxy, there is nothing to do: custom domains work by themselves. This page explains why the proxy is needed, and what to do when your server uses something else.

Why a custom domain needs its own certificate#

When a visitor opens https://help.yourshop.com, the browser asks the server for a certificate made for exactly help.yourshop.com. A certificate is a small file that proves the server may use that name. The certificate for your own address, such as chat.example.com, does not count. With the wrong certificate, the browser shows a security warning instead of the chat.

So every custom domain needs a certificate of its own. Agent owners add domains whenever they want, so the server must get each certificate by itself, at the moment the domain is first used.

Most web servers can't do this:

• nginx, Apache and Traefik only use certificates that already exist on the disk. They can't get one for a name they have never seen.
• Certbot gets certificates, but only when someone runs it for a domain.

Caddy can. It is a web server that gets a certificate the first time a browser asks for a new name. It uses Let's Encrypt, which is free, and it renews each certificate by itself. Before it asks Let's Encrypt, Caddy asks Chatvia: "is this the saved domain of an agent?" Only then does it get the certificate. So nobody can make your server collect certificates for names of their own.

That is why the installer puts Caddy in front of Chatvia.

How it works#

1. An agent owner saves help.yourshop.com, and adds a CNAME record that points it to your Chatvia address.
2. Chatvia checks the domain every few minutes. The first check opens https://help.yourshop.com.
3. Caddy sees a name it has no certificate for. It asks Chatvia at /custom-domains, gets a yes, and gets the certificate from Let's Encrypt in a few seconds.
4. The check reaches Chatvia over HTTPS, and the domain turns Active.

Caddy also gets and renews the certificate for your own address.

Requirements:

• A license key on the install. Without one, saved domains stop working.
• Ports 80 and 443 open to the internet. Let's Encrypt checks each domain on one of them before it gives a certificate.

With the installer#

Complete install#

The complete install puts Caddy on ports 80 and 443 when you choose HTTPS. nginx answers Caddy on 127.0.0.1:8081. Custom domains are on from the start: Settings → Platform → Custom domains says This server gets certificates for new domains by itself.

An install from before Caddy uses Certbot. To move it to Caddy, run the installer again:

curl -fsSL https://chatvia.ai/install.sh | sudo bash

Choose Move HTTPS from Certbot to Caddy. The installer:

• installs Caddy, and writes /etc/caddy/Caddyfile
• moves nginx to 127.0.0.1:8081, and starts Caddy on ports 80 and 443
• waits until Caddy has the certificate for your address
• stops Certbot's renewals, and tells Chatvia that Caddy is in front

If Caddy gets no certificate, nothing changes: nginx and Certbot serve HTTPS as before. Automatic updates never do this move. You choose it.

Docker install#

Choose ChatVia.ai handles HTTPS when the installer asks where people open ChatVia.ai (or pass --https builtin). The stack then runs Caddy as its proxy service, on ports 80 and 443. See HTTPS built in.

An install that uses its own proxy can switch at any time:

./manage https on

Ports 80 and 443 must be free: stop your own proxy first. ./manage https off goes back.

Your own web server#

When ChatVia.ai runs behind a web server of yours, that web server holds the certificates. You have two choices.

Caddy with on-demand certificates#

Caddy does everything above. The Chatvia repository has this setup as docker/Caddyfile.example:

{
    on_demand_tls {
        ask http://127.0.0.1:8000/custom-domains
    }
}

chat.example.com {
    reverse_proxy 127.0.0.1:8000
}

https:// {
    tls {
        on_demand
    }
    reverse_proxy 127.0.0.1:8000
}

• Replace chat.example.com with your Chatvia address.
• Replace 127.0.0.1:8000 with where Chatvia listens: APP_PORT on a Docker install.
• ask is where Caddy asks "may I get a certificate for this name?". Chatvia says yes only for a domain an agent saved.

Set TRUSTED_PROXIES in .env, so Chatvia knows a visitor came over HTTPS. Then turn on Settings → Platform → Custom domains.

nginx, Apache or Traefik: one domain at a time#

These can't get certificates on demand. You can still use custom domains, by adding each domain by hand when an agent owner asks for one:

1. Add the domain to your web server, the same way as your own address. For nginx, add it to server_name in the Chatvia site.
2. Get a certificate for it, for example sudo certbot --nginx -d help.yourshop.com.
3. Ask the agent owner to click Check again on the Deploy page.

When your address is behind Cloudflare#

When your own address runs through a CDN such as Cloudflare with the proxy on (the orange cloud), its DNS points at the CDN, not at your server. The CDN only answers for names in its own customers' accounts, so a customer's domain that points at your address gets an error from the CDN.

Give customers a second address that points straight at your server:

1. Add a DNS record, such as domains.example.com, that points at your server's IP address. With Cloudflare, set it to DNS only (the grey cloud).
2. Open ports 80 and 443 to everyone. A firewall that lets in only the CDN's addresses also blocks Let's Encrypt and your customers.
3. In the admin panel, enter domains.example.com under Settings → Platform → Custom domains → CNAME target.

The Deploy page then tells agent owners to point their domain at domains.example.com. Your own address stays behind the CDN.

Check that it works#

On the agent's Deploy page, a domain shows Active when everything is right. If it shows Not working yet, the message says why:

• "…this server has no certificate for it yet." The domain points to your server, but no certificate came. On a complete install, read Caddy's log: sudo journalctl -u caddy -n 100. On Docker: ./manage logs proxy. Often port 80 or 443 is blocked, or the switch in the admin panel is off.
• "…not from this server." The domain points to another server. The agent owner must fix the DNS record.

You can also ask Chatvia what it tells Caddy. On a complete install, run:

curl -i "http://127.0.0.1:8081/custom-domains?domain=help.yourshop.com"

On a Docker install, use your APP_PORT instead of 8081.

200 means Caddy may get a certificate for the name. 404 means it is not a saved domain, the switch is off, or the install has no license key.

Good to know#

• Custom domains serve only the agent's chat. The dashboard and the admin panel stay at your own address.
• Chatvia checks new domains every ten minutes for two days, and active domains once a day, with the scheduler. See the scheduler.
• Without a license key, or with the switch off, saved domains stop working and the chats' links go back to your own address. The domains stay saved.
• Let's Encrypt allows many certificates, but not unlimited: up to 300 new certificates for one account every three hours. That is far more than agent owners add.