DNS & subdomains
Tether uses subdomains to route traffic to client tenants. You need two DNS A records — one for the root domain and one wildcard that covers all subdomains.
Required DNS records
Add the following records at your DNS provider. Both should point to your server's public IP address:
| Type | Name / Host | Value | TTL |
|---|---|---|---|
| A | atechsolutions.org (or @) | Your server IP | 300 |
| A | *.atechsolutions.org (or *) | Your server IP | 300 |
Replace atechsolutions.org with your own domain. Set BASE_DOMAIN=yourdomain.com in .env to match.
Without the wildcard * A record, you would need to manually add a DNS record for every client you create. The wildcard means acme.yourdomain.com, nexus.yourdomain.com, and any other slug you create all resolve automatically.
Verify DNS propagation
DNS changes can take from a few seconds to 48 hours to propagate, depending on your TTL settings and provider. Verify with:
bash# Check the root domain dig atechsolutions.org A +short # Should return your server IP # Check a wildcard subdomain dig acme.atechsolutions.org A +short # Should also return your server IP # Using nslookup (Windows-friendly) nslookup acme.atechsolutions.org
Using Cloudflare
If your domain is managed through Cloudflare (common for MSPs), there are a few important notes:
- Add the root A record (
@) and wildcard A record (*) in the DNS tab - Wildcard records with Cloudflare proxying (orange cloud) require a Pro plan or above. On the free plan, wildcard records can only be DNS-only (grey cloud).
- If using DNS-only (grey cloud), you must handle SSL yourself with Certbot — see Reverse proxy & HTTPS
- If using Cloudflare proxying (orange cloud), set SSL/TLS mode to Full (strict) and make sure Tether has a valid origin certificate
On Cloudflare's free plan, wildcard DNS records (*) can only be set to DNS-only (grey cloud, no proxying). This is fine — your SSL comes from Certbot's wildcard certificate instead. Just make sure the nginx config is correct.
Custom domains for clients
Clients can optionally use a fully custom domain instead of a subdomain — for example,
assets.acme.com instead of acme.atechsolutions.org. This requires:
- The client adds a CNAME record at their DNS provider:
assets.acme.com CNAME atechsolutions.org - You register the custom domain in Tether via the API:
POST /api/tenants/{id}/domains - Once DNS propagates, verify it in Tether:
PUT /api/tenants/{id}/domains/{did}/verify
After verification, assets.acme.com will resolve to the Acme tenant just like acme.atechsolutions.org.
A custom domain needs its own SSL certificate. The easiest approach is to have the client point their domain through Cloudflare (which provides the SSL). Alternatively, add the custom domain to your Certbot certificate and renew.
Local development
For local development without a real domain, you can test subdomain routing by editing /etc/hosts:
bash# Add to /etc/hosts 127.0.0.1 localhost 127.0.0.1 acme.localhost 127.0.0.1 nexus.localhost
Then set BASE_DOMAIN=localhost in your .env and run Tether on port 8000. Access client tenants at http://acme.localhost:8000.
The /etc/hosts file does not support wildcards. You must add each subdomain individually for local development. Consider using a tool like dnsmasq for a more scalable local dev setup.