SSL Certificates
HTTPS options for your dashboard, from reusing an existing host certificate to a free trusted subdomain.
Your Astervis dashboard is served over HTTPS on a single port — https://<domain-or-IP>:8443. The nginx container terminates TLS using whatever certificate the installer placed at /opt/astervis/nginx/ssl/server.crt and its matching server.key. You don't normally touch any of this by hand: during the install wizard, Astervis picks the best certificate option available on your server and wires up nginx for you. This page explains the four options, when to choose each one, and how to regenerate, swap, renew, and troubleshoot a certificate later.
The only externally exposed port is 8443. Everything else — the backend, admin
UI, TimescaleDB, Redis, the CDC service — binds to 127.0.0.1. So the certificate
that matters is the one nginx presents on 8443, and that's the one we're configuring
here.
The four options, in priority order
During Step 3/4 — Configuration, the wizard shows a domain/SSL menu and works down this list, from "most trusted, least work" to "always works." The first option that succeeds wins.
Reuse an existing host certificate (recommended when available)
If your server already runs a domain with a valid certificate — issued by
certbot, an Apache/httpd vhost, or FreePBX's certificate manager — the wizard
detects it and lists it first, as something like
Use detected domain pbx.company.com — existing SSL until 2026-09-01 (DNS ✓).
Pick it and Astervis copies the live certificate and key into nginx/ssl/
(resolving Let's Encrypt live/ → archive/ symlinks along the way). Because the
cert is already trusted by browsers, there's no warning and nothing to issue. A
daily systemd timer then keeps it fresh after your own renewals (see below). Added
in installer v0.0.86.
Free *.web.astervis.io subdomain (DNS-01, no port 80 needed)
The wizard asks for a short company identifier and creates a trusted
{company}.web.astervis.io subdomain for you, with a real certificate issued via a
DNS-01 challenge through the central Astervis API. Because validation happens
over DNS, port 80 doesn't need to be open or free — this is the recommended
choice whenever ports 80/443 are already taken by another web server.
Let's Encrypt (HTTP-01 on port 80)
For an IP-only setup or a custom domain that already points at this server, the installer issues a free Let's Encrypt certificate using the HTTP-01 challenge on port 80. Port 80 must be reachable from the internet for the duration of the challenge.
Self-signed fallback
If none of the above succeed, Astervis generates a self-signed certificate (with your domain or IP as the common name) so the dashboard still works over HTTPS. Browsers show a "Your connection is not private" warning — the connection is still encrypted, the certificate just isn't vouched for by a public authority.
All four paths end up writing the same two files — server.crt and server.key in
/opt/astervis/nginx/ssl/ — and the same nginx config. Switching options later is
just a matter of replacing those files (or re-running the relevant step) and
restarting nginx.
Which option should I pick?
Most of the time the wizard's default ordering is the right answer. Use this when you need to decide for yourself:
Server already has a trusted domain
Reuse the existing host certificate. Zero issuance, no browser warning, and the daily timer keeps it in sync with your own renewals.
Ports 80 and 443 are busy
Use the free *.web.astervis.io subdomain. DNS-01 validation means nothing has to listen on port 80.
Bare IP, no domain
Let's Encrypt over HTTP-01 — but it can only issue if port 80 is free, because public CAs forbid DNS-01 for IP addresses.
Air-gapped or no public DNS
Self-signed. Fully encrypted; you (or your browser policy) accept the certificate once.
A certificate for a bare IP needs port 80. Public CAs only issue IP certificates
via HTTP-01 (port 80) or TLS-ALPN-01 (port 443) — DNS-01 is forbidden for IP
addresses. If another web server (apache2, ispmanager, FreePBX) already holds 80 and
443, Let's Encrypt cannot issue an IP certificate. On those hosts, use the free
*.web.astervis.io subdomain or point a real domain at the server.
The daily cert-sync timer
When you reuse an existing host certificate, the source certificate (for example
/etc/letsencrypt/live/pbx.company.com/) keeps renewing on its own schedule through
your certbot, Apache, or FreePBX setup. Astervis doesn't manage that renewal — it just
needs to copy the renewed file back into nginx/ssl/ and reload nginx afterward.
That's exactly what the astervis-cert-sync.timer systemd timer does. Once a day
it re-copies the source certificate into /opt/astervis/nginx/ssl/ and restarts the
nginx container if the file changed. The script it runs lives at
<install_dir>/cert-sync.sh.
# See when the timer last ran and when it fires next
systemctl status astervis-cert-sync.timer
systemctl list-timers astervis-cert-sync.timer
# Force a sync right now (e.g. just after renewing the source cert manually)
sudo systemctl start astervis-cert-sync.serviceThe timer only exists for the reuse-existing-certificate path. The
*.web.astervis.io and Let's Encrypt paths renew through their own ACME flow, and
self-signed certificates are long-lived and don't renew on a short cycle.
Regenerating, replacing, and renewing
Switch options on an installed server
SSL selection is part of the install wizard, and the install is checkpointed in
/opt/astervis/.install-state.json. The cleanest way to switch from, say, a
self-signed certificate to a *.web.astervis.io subdomain is to resume the install and
choose the new option when you reach the configuration step:
sudo astervis-installer install --resumeInstall your own custom certificate
If you have a certificate from your own CA or a commercial provider, drop the files in place and restart nginx. Astervis expects a PEM certificate (with the full chain) and an unencrypted private key.
Copy your certificate and key into place
sudo cp fullchain.pem /opt/astervis/nginx/ssl/server.crt
sudo cp privkey.pem /opt/astervis/nginx/ssl/server.keyUse the full chain (leaf + intermediates) for server.crt, or some browsers
will report an incomplete chain.
Lock down permissions
The private key must not be world-readable.
sudo chmod 600 /opt/astervis/nginx/ssl/server.key
sudo chmod 644 /opt/astervis/nginx/ssl/server.crtRestart nginx to load the new certificate
cd /opt/astervis
sudo docker compose restart nginxDon't hand-place a custom certificate while you're also on the reuse path — the daily
astervis-cert-sync.timer will overwrite it with the detected host certificate on its
next run. If you're managing the certificate yourself, disable the timer first:
sudo systemctl disable --now astervis-cert-sync.timer.
Renewal at a glance
| Option | How it renews | Your action |
|---|---|---|
| Reuse existing host cert | Your own certbot/Apache/FreePBX renews the source; the daily timer copies it in | None — keep your existing renewal working |
*.web.astervis.io subdomain | ACME via the central API | None |
| Let's Encrypt (HTTP-01) | ACME on port 80; certificates last 90 days | Keep port 80 reachable |
| Self-signed | Long-lived, no short renewal cycle | Regenerate via the wizard if needed |
| Custom certificate | You renew it externally | Re-copy the files and restart nginx |
Verifying the certificate
After any change, confirm nginx is serving what you expect.
openssl x509 -in /opt/astervis/nginx/ssl/server.crt -noout -subject -issuersubject shows the domain or IP the certificate is for; issuer tells you whether
it's Let's Encrypt, your own CA, or self-signed (where issuer equals subject).
You can also check the certificate the way a browser would, by name, from another machine:
echo | openssl s_client -connect pbx.company.com:8443 -servername pbx.company.com 2>/dev/null | openssl x509 -noout -subject -enddateTroubleshooting
Still stuck? Every install writes a full log (the path is printed as Logs: ... at
install time), and on a startup failure the installer dumps per-container diagnostics
into it. Sending that single file is the fastest way to get help.
Where the files live
Next steps
Last updated on