Your own domain¶

Every app answers on <app>.<you>.allocus.dev with HTTPS from the moment it deploys. That hostname never goes away. A custom domain is additional — your app answers on both.

Point the DNS first¶

This is the one step that has to happen before you deploy, and Allocus will refuse the deploy if you skip it. Two options:

A subdomain (shop.example.com) — use a CNAME:

shop.example.com.   CNAME   shop.you.allocus.dev.

An apex domain (example.com) — use an A record, because DNS doesn't allow a CNAME at the apex. Both records, filled in with your own box and apps, are on your dashboard under Your own domain — copy them straight from there:

example.com.   A   51.158.78.224

Prefer the CNAME wherever you can. It follows your box automatically — including through a rebuild, which changes the IP. An A record is a number you own and have to maintain.

Declare it in `allocus.yaml`¶

name: shop
port: 8080
domains:
  - shop.example.com

Multi-service stacks work the same way — domains: is app-level, not per-service, and your existing path: routing applies to each domain identically:

name: shop
domains:
  - shop.example.com
  - www.example.com          # a second name for the same app is fine
services:
  web:
    build: ./frontend
    port: 3000
    expose: true             # → shop.example.com/
  api:
    build: ./backend
    port: 8000
    path: /api               # → shop.example.com/api

Then deploy as usual:

allocus deploy

Nothing else to configure. The certificate is requested during the deploy and is usually live within a few seconds.

What happens on the first deploy¶

Your *.allocus.dev hostname is covered by a wildcard certificate that already exists, so it is valid instantly. A custom domain can't work that way — the certificate has to be issued for your specific name, and Let's Encrypt only issues it after checking that the name really does point at your box.

That check is why the DNS has to come first, and why a deploy with an unpointed domain is rejected rather than accepted-and-broken:

$ allocus deploy
error: shop.example.com does not resolve. Point it at this box first
(CNAME to your app's allocus.dev hostname, or an A record to 51.158.78.224),
then deploy again.

If it resolves somewhere else, you'll be told where, which is usually enough to spot the typo or the record you forgot to delete.

Rules worth knowing¶

One domain, one app. A hostname can be held by exactly one app at a time, across all of Allocus. Deploying a domain someone else already routes fails with a clear error; so does pointing the same domain at two of your own apps.

Removing it is a deploy. Delete the entry from domains: and deploy — the hostname is released immediately and is free for another app, or another account, to claim. There is no separate command and nothing to clean up.

Both www and the apex need listing. They're two names. If you want example.com and www.example.com to both work, put both in domains: and give both a DNS record. Allocus doesn't redirect one to the other for you.

If you rebuild your box, check your A records. A rebuild gets a new IP address. CNAMEs follow on their own; A records don't, and an apex domain pointing at your old address will simply stop working until you update it.

Limits¶

HTTP only for validation. Port 80 has to be reachable for the certificate to be issued and renewed. It is, by default — just don't put anything in front of your box that blocks it.
No wildcard custom domains. *.example.com isn't supported; list the names you want.
No redirects or aliases. Every domain in the list serves the app directly. If you want www to redirect to the apex rather than serve alongside it, do that in your app.