Domains and HTTPS
Visitors reach a service through its domains, always over HTTPS. Each domain needs a certificate that covers it, which an admin uploads once under SSL Certificates.
Add a domain
Point the domain at the first server
Create a DNS A record for the domain with the IP address of your first server, the one you installed Harblet on. All web traffic enters there, also for services that run on other servers.
app.example.com. A 203.0.113.10
Upload a certificate
If no certificate covers the domain yet, an admin uploads one. See Certificates.
Add the domain to the service
Open the service, go to Domains, enter the domain, for example app.example.com, and click Add domain.
The domain works right away, without a deployment. Harblet sends its traffic to the service's port. Requests over plain HTTP are redirected to HTTPS.
- The service needs a port. A service without one can't have domains. Set it under Settings and deploy. To remove the port later, remove the service's domains first.
- A domain belongs to one service. It can't be used by two services, or by a service and Harblet itself.
- Wildcard domains such as
*.example.comcan't be added to a service. Add each subdomain instead. One wildcard certificate covers them all. - A service can have several domains, for example
example.comandwww.example.com.
To remove a domain, click its trash button and confirm. It stops pointing at the service right away.
Certificates
Harblet serves your own certificates. It doesn't request certificates from Let's Encrypt at the moment. Use a certificate from your provider or your company's CA, or get one from Let's Encrypt yourself, for example with Certbot.
Upload a certificate
Open SSL Certificates
Click SSL Certificates in the sidebar, then Upload certificate.
Paste the certificate
Paste the certificate in PEM format, followed by its intermediate certificates:
-----BEGIN CERTIFICATE-----
(your certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(intermediate certificate)
-----END CERTIFICATE-----
With Certbot, that's the content of fullchain.pem.
Paste the private key
Paste the private key in PEM format, without a passphrase. With Certbot, that's privkey.pem.
Upload it
Click Upload certificate. Harblet checks that the key belongs to the certificate and that the certificate is valid, then uses it right away for the domains it covers, following the rules below.
Which domains a certificate covers
The Covers column lists the domain names in the certificate, and Used by shows how many domains use it.
- A name like
app.example.comcovers exactly that domain. - A wildcard like
*.example.comcovers one level of subdomains:app.example.comandapi.example.com, but notexample.comitself and nota.b.example.com.
When several certificates cover a domain, Harblet uses one with the exact name over a wildcard, and otherwise the one that expires last. Expired certificates never count.
Renew a certificate
Upload the renewed certificate before the old one expires. Harblet switches every domain it covers to the new certificate right away. Then delete the old one.
The Expires column marks certificates that expire within 30 days with Expires soon, and past ones with Expired.
Delete a certificate
Click the trash button of a certificate and confirm. Harblet refuses if a domain would be left without a valid certificate, including Harblet's own domain. Upload the replacement or remove the domain first.
Troubleshooting
| Problem | What to check |
|---|---|
| "This service has no port" | Set the service's port under Settings and deploy. |
| "Upload a certificate for this domain under SSL Certificates first.", or for members "Ask an admin to upload a certificate for this domain first." | No valid certificate covers the domain. Upload one, or check that a wildcard covers this level of subdomain. |
| "This domain is already used by a service." | Remove the domain from the other service first. |
| "This domain is used by Harblet itself." | Harblet's own domain can't be added to a service. Use another subdomain. |
| "The certificate has no DNS names" | Harblet reads the domains from the certificate's subject alternative names. Use a certificate that lists the domain there, not only as its common name. |
| "This private key does not belong to the certificate" | Paste the key that belongs to this certificate. With Certbot, that's privkey.pem next to fullchain.pem. |
| "Remove the passphrase from the private key" | Export the key without a passphrase, for example with openssl pkey -in key.pem -out key-plain.pem. |
| "The certificate has expired" or "The certificate is not valid yet" | Check the certificate's dates and upload a current one. |
| The browser can't reach the domain | Check that the A record points at the first server and that ports 80 and 443 are open in its firewall. |
| The browser shows the wrong certificate | Make sure the uploaded certificate covers the domain and hasn't expired. If an expired certificate is still listed, delete it. |