Setting the Panel Hostname (HTTPS with Let's Encrypt)

When Opterius is installed on a fresh server, the panel is reachable only by IP address (e.g. https://1.2.3.4:8443) with a self-signed certificate. Browsers display a warning, and the URL is hard to remember and share.

The Panel Hostname page lets you switch to a real subdomain with a valid Let's Encrypt SSL certificate in a single click. No SSH, no manual nginx editing.

Where to find it#

Open the panel in Server Mode, then in the admin sidebar click Panel Hostname.

You'll see:

• The current panel URL (the address you're actually accessing — not what's in .env).
• A green badge if you're already on a hostname with valid SSL, or an amber warning if you're still on the IP.
• A form to enter a new hostname and your admin email.

Before you start#

Three things must be true before clicking Apply:

1. DNS A record exists. Add a record like panel.example.com → <server IP> and wait for propagation. Verify with:

   dig +short panel.example.com
   

   It must return your server's public IP. A wildcard record (*.example.com → <IP>) also works — panel.example.com will resolve automatically.

2. Port 80 is open in the firewall. Let's Encrypt validates ownership over HTTP for a few seconds. If port 80 is blocked, certificate issuance fails. Check with:

   ufw status                    # Debian/Ubuntu
   firewall-cmd --list-ports     # RHEL family
   

3. Bookmark the new URL. After applying, the panel rebinds to the new hostname. The old IP-based URL stops responding immediately.

Applying a hostname#

1. In Panel Hostname, type the hostname (e.g. panel.example.com).
2. The admin email is pre-filled with your account email — change it if you want renewal notifications to go elsewhere.
3. Click Apply hostname & issue SSL.
4. Wait 30–60 seconds. The agent runs:
   • DNS check (verifies the hostname resolves to this server).
   • certbot certonly --standalone (issues a Let's Encrypt cert).
   • Rewrites /etc/nginx/sites-available/opterius-panel.conf with the new cert and server_name.
   • Reloads nginx.
   • Updates APP_URL in /opt/opterius/.env.
   • Clears the Laravel config cache.

When it succeeds, a confirmation page loads with a button to the new URL and an automatic redirect after 6 seconds.

What happens to the old IP URL#

The new nginx vhost only answers requests for the configured server_name. Requests to the bare IP on port 8443 will return ERR_EMPTY_RESPONSE in your browser. This is expected. Your panel is fine — just open the new hostname URL.

If you want to keep IP access working as well (not recommended for security reasons), you'd need to add a second server { listen 8443 ssl default_server; ... } block by hand.

Auto-renewal#

Let's Encrypt certificates expire after 90 days. The installer enables certbot.timer, which runs twice a day and renews any cert in the last 30 days of its life. A deploy-hook reloads nginx after a successful renewal.

To verify the timer is active:

systemctl list-timers | grep certbot

To force a renewal test (without actually renewing):

certbot renew --dry-run

Troubleshooting#

"DNS for X points to Y, not this server"#

The agent compared the A record to the server's public IP and they don't match. Fix the DNS record and wait for propagation (sometimes 5–15 minutes), then try again. If the server has no public IPv4 (only IPv6), see IP Address Management.

"certbot failed"#

The most common causes:

• Port 80 blocked in the firewall (UFW, firewalld, or a cloud-provider firewall like Linode Cloud Firewall, AWS Security Groups, Hetzner firewall). Open port 80 inbound for 0.0.0.0/0.
• DNS not yet propagated. Even when dig from your laptop returns the right IP, Let's Encrypt's resolvers may still see the old value. Wait a few minutes and retry.
• Rate limit hit. Let's Encrypt limits 5 cert issuances per hostname per week. If you've been testing repeatedly, switch to the staging environment first.

Page loads at the new URL but shows a 502 / 504#

Means nginx accepted the new vhost but the panel's PHP-FPM socket is in a non-default location. Check:

nginx -t
ls /run/opterius-panel.sock /run/php/php*-fpm.sock

If your install uses the system PHP-FPM socket instead of the dedicated panel socket, the rewritten vhost needs a manual edit to point at the right socket.

I changed my mind — switch back to IP#

Restore the original self-signed vhost from your installer, or just run the Panel Hostname form again with a different hostname. There's no "revert to IP" button — the assumption is that once you have a hostname, you want to use it.

Related#

• Adding Servers
• The Admin Dashboard
• Installation