The Domains tab puts your app on your own domain, with a free HTTPS certificate. You do not write any web server config or certificate commands.
Find what you need
| I want to | Instead of doing | Go to |
|---|---|---|
| Put my app on a domain | Write an nginx file, run certbot, set up renewal | Put your app on a domain |
| Choose nginx or Traefik | Read both sets of docs | Choose a web server |
| Check my certificate | openssl s_client, certbot certificates | Read the domain list |
| Check my DNS | dig app.example.com | Verify DNS |
| Send one domain to another | Write a redirect by hand | Redirect a domain |
| Run several copies behind one domain | Write an upstream block | Load balancer |
| Fix a failed certificate | Read certbot logs | Troubleshooting |
Put your app on a domain
Point DNS at your server
At your DNS provider, add an A record for your host name, such as app.example.com, that points to the public IP address of your server. The change can take a few minutes to reach everyone.
Also check that ports 80 and 443 are open. On a cloud server, that often means the cloud firewall or security group as well.
Prepare a web server
You only do this once for each server. A web server receives visitors on ports 80 and 443, and sends them to the right container.
If the chip at the top says Set up a web server, click it. If it already shows nginx or Traefik, skip this step.
Choose nginx or Traefik, and confirm.
Add the domain
Click Add Domain at the top right. On a server with no domains yet, the same button is also in the middle of the tab.
Fill in the form:
| Field | What to enter |
|---|---|
| Domain name | The full host name, such as app.example.com |
| Label | Optional. A note for yourself |
| Target | The container and the port your app listens on inside it, such as web:3000. For a stack, use stack/service:3000 |
| Enable SSL | Leave it on. It gets a free Let's Encrypt certificate and redirects visitors from HTTP to HTTPS |
| Auto-renew | Leave it on, so the certificate renews before it expires |
The form shows the exact route CtrlOps will write. If the server has no web server yet, it says No route. CtrlOps does not change the web server., so prepare a web server first. Click Add domain.
Check the certificate
The ssl column shows requested while CtrlOps gets the certificate, then valid. This can take a few minutes. Then open your domain in a browser.
If DNS is not ready, the status stays on pending, and CtrlOps asks for the certificate once DNS points here. Keep CtrlOps open, or open it again after DNS is ready.
Choose a web server
| nginx | Traefik | |
|---|---|---|
| Best for | Most servers. This is the recommended choice | Servers where you want everything in containers |
| Runs as | A service on the server | A container named ctrlops-proxy |
| Certificates | certbot gets them and renews them 30 days before expiry | Traefik gets and renews them by itself |
| Works with Deployments | Yes, Deployments uses the same nginx | No |
| Needs | Root or sudo | Docker with root access |
A server uses one web server for all its domains. If nginx already runs on the server, CtrlOps uses it, and you do not choose.
What stays on your server
CtrlOps lists this before it installs anything, and Show commands shows the exact commands.
- With nginx: the nginx service, a way to renew certificates (the server's certbot timer, or one root cron line that runs twice a day), and domain files in
/var/lib/ctrlops/domains. - With Traefik: the
ctrlops-proxycontainer, which restarts with Docker, and the same domain files. - Firewall: if the server uses ufw or firewalld, you can choose to open ports 80 and 443.
Deleting a domain removes its files. For Traefik, Remove proxy removes the container once no domain uses it.
Read the domain list
The top shows how many domains are healthy and how many need attention. The chip next to them shows your web server and whether renewal is on.
| ssl status | What it means | What to do |
|---|---|---|
| valid | The certificate is good | Nothing |
| requested | CtrlOps is getting a certificate | Wait a minute |
| pending | Waiting for DNS to point here | Check your A record |
| expiring | It is close to its end date | Check that renewal is on. It should renew by itself |
| expired | The certificate has ended, and visitors see a warning | Choose Issue certificate |
| failed | CtrlOps could not get one | Open the domain, read why, and choose Retry |
| wrong cert | The certificate on the site is for another name | Choose Issue certificate |
| none | SSL is off for this domain | Choose Issue certificate if you want HTTPS |
The target column shows where traffic goes, with a dot for the state of the container. Not managed here marks a site from another file on the server. CtrlOps shows it so you know the name is taken, but it does not change it.
Manage a domain
Click a row to see its details, or open its menu:
| Action | What it does |
|---|---|
| Edit domain | Changes the target or the settings |
| Verify DNS | Checks that the name points to this server |
| Issue certificate | Asks for a certificate |
| Disable SSL | Turns off HTTPS for this domain |
| Turn auto-renew off | Stops renewal for this domain. Not available with Traefik, which renews by itself |
| Open link | Opens the domain in your browser |
| Apply again | Writes the route again, if it went missing |
| Delete domain | Removes the route. You can tick Also delete the certificate |
The details also have Add an expiry alert, which opens Alerts so you get a message before a certificate runs out.
Redirect a domain to another
In Target, type 301 → app.example.com to send visitors from this domain to another, keeping the path. Use 302 for a temporary redirect, or a full https:// address to send them to one page. You can type -> in place of the arrow.
Add a domain from a container
Open the container, go to its Domain tab, and click Add domain. Type the Domain name and the Port, keep HTTPS on, and click Add. The tab also shows the IP address of the server, with Copy IP, for your A record.
Add a domain when you create a container
When you create a container or deploy a stack, click Link in the domain column of the Container stack table. CtrlOps adds the domain after the container starts.
Besides the domain name and HTTPS, the panel has Verify DNS, Redirect HTTP → HTTPS, and Auto-renew. If the server has no web server yet, CtrlOps asks to install one when you create.
Load balancer runs several copies of a service behind one domain. Set the Replicas and how to share visitors: round robin, least connections, or ip hash / sticky. Replicas need a Compose stack, and the service cannot have a fixed container name.
Tips
- Set up DNS before you add the domain. It saves you from failed checks and the Let's Encrypt limit.
- Use nginx if you also use Deployments. Both share one web server, so nothing fights over ports 80 and 443.
- Add an expiry alert. Renewal is automatic, but an alert tells you if it ever stops.
Troubleshooting
Most failures show Show details with the Likely cause, Retry where it helps, and Copy report. Send that report with any support question.
The domain does not reach this server on port 80.
Either DNS points to another server, a cloud firewall or security group closes port 80, or another server answered. Let's Encrypt needs port 80 to check your domain, so open it, then choose Retry.
No A record, or DNS points to another server
Add or change the A record at your DNS provider, then choose Verify DNS again. If you also have an AAAA record, make sure it points here too, because Let's Encrypt tries IPv6 first.
The domain is behind the Cloudflare proxy.
CtrlOps cannot see the server behind Cloudflare, so it cannot confirm your DNS. If the certificate fails, set the record to DNS only until the certificate is ready.
Let's Encrypt refused: too many requests for this name.
Let's Encrypt limits requests, and allows only 5 failed checks per hour for a name. Fix the cause, wait, and try again later.
Let's Encrypt could not read the test file on this domain.
Something other than this web server answered, such as another server or a CDN. Check your DNS and any proxy in front of the server.
No certificate after 3 minutes.
With Traefik, it keeps trying by itself every few minutes. Check DNS and port 80, then read the details on the domain.
Another program uses ports 80 and 443.
Only one program can use these ports. CtrlOps adds Docker domains through nginx or Traefik only, so it cannot use Apache, another proxy container, or a PM2 app on port 80. Stop that program, or move it to another port.
This nginx does not read /etc/nginx/conf.d.
CtrlOps adds routes as files in that folder. Add an include line for conf.d to your nginx config, then click Read again.
nginx did not accept the new file. CtrlOps put the old file back.
Your sites stayed up. Open Show details to read the error. If the message is The nginx configuration of this server has an error now. CtrlOps changed nothing., fix that error first, and then try again.
SELinux stops nginx from connecting to the container.
Turn on the option Allow nginx to connect to local ports (SELinux) when you set up the web server.
The route is ready, but the container does not answer.
The domain works, but the app does not reply. Check that the container runs, and that the port in the target is the one the app listens on. The logs usually show why.
Target not found
CtrlOps cannot find that container. It may have been renamed or deleted. Choose Edit domain and set the target again.
This container has no port on the host.
A container on the none network, or on a macvlan or ipvlan network, has no port the web server can reach. Move it to a bridge network.
Certificates do not renew on this server.
The renewal timer or cron line stopped. Click Start renewal. Your certificates keep working until they expire, so fix this soon.
Traefik needs Docker with root access.
This Docker runs without root, so Traefik cannot use ports 80 and 443. Choose nginx instead.
Frequently Asked Questions
Do I need to keep CtrlOps open for certificates to renew?
No. Renewal runs on the server. With nginx, certbot renews a certificate 30 days before it expires. Traefik renews certificates by itself. You only need CtrlOps to set things up or check on them.
Should I choose nginx or Traefik?
Choose nginx unless you have a reason not to. It is the recommended choice, and the Deployments tab uses the same nginx. Traefik runs in a container and needs Docker with root access.
Will adding a domain break my existing sites?
No. With nginx, CtrlOps writes one new file, tests it, and reloads nginx, so the sites that run now stay up. If nginx does not accept the file, CtrlOps puts the old one back.
Can I use a wildcard domain or an IP address?
No. CtrlOps needs a full host name, such as app.example.com. It does not support wildcard names, and it does not add a domain for an IP address.
Does a container need a published port to use a domain?
Yes. The web server reaches the container through a port on the server. If the port is not published, CtrlOps offers to publish it on 127.0.0.1 only, so the app is reachable through your domain and not through the port. This restarts the container.
