Skip to content

SSL/HTTPS Certificate Setup

Overview

Osprey supports three methods for enabling HTTPS on your server. A server restart is required after any certificate change takes effect.

!!! info "Who can manage SSL?" Only users with the Workspace Admin role have access to the SSL / HTTPS settings tab.

Accessing SSL Settings

  1. Navigate to Settings (top navigation)
  2. Click the SSL / HTTPS tab
  3. The current certificate status is displayed at the top of the page

Certificate Status Banner

When you open the SSL tab, the status banner shows:

Field Description
Subject The domain name the cert is issued to
Expires Expiry date and days remaining
Type Self-Signed (yellow) or CA Signed (green)

!!! warning If no certificate is configured, the banner will show an error in red prompting you to generate or upload one.

Method 1 — Generate a Self-Signed Certificate

Best for: local or on-premise deployments, internal testing, air-gapped environments.

Steps

  1. Click Generate Self-Signed Cert
  2. The certificate is generated automatically — no input required
  3. Restart the server to apply

Browser Warnings

Self-signed certificates will trigger a security warning on first visit. This is expected.

Browser How to proceed
Chrome / Edge Click Advanced → Proceed to [site] (unsafe)
Firefox Click Advanced → Accept the Risk and Continue

Method 2 — Request a Let's Encrypt Certificate

Best for: public-facing servers with a registered domain name. Free, trusted by all browsers — no warning shown to users.

Prerequisites

  • A public domain name (e.g. osprey.yourcompany.com)
  • The server must be reachable on port 80 from the internet (for ACME HTTP challenge)

Steps

  1. Enter your Domain (e.g. osprey.yourcompany.com)
  2. Enter your ACME Email — used for expiry notifications from Let's Encrypt
  3. Click Save to store the configuration
  4. Click Request Certificate to initiate the ACME challenge
  5. Wait up to a minute while the certificate is issued
  6. Restart the server to apply

!!! warning Save your domain and email first before requesting. The values persist so you can renew without re-entering them.

Method 3 — Upload a Custom Certificate

Best for: enterprise environments where certificates are issued by your IT department or a commercial CA (e.g. DigiCert, Entrust, GlobalSign).

Prerequisites

  • A certificate file in .pem or .crt format
  • A private key file in .pem or .key format
  • Both files must correspond to the same key pair

Steps

  1. Under Upload Custom Certificate, attach your Certificate File
  2. Attach your Private Key File
  3. Click Upload Certificate
  4. Restart the server to apply

!!! note The existing certificate is automatically backed up before being replaced. You can restore it using Revert to Previous if needed.

Reverting to a Previous Certificate

If an uploaded certificate causes issues:

  1. Click Revert to Previous
  2. The most recent backup is restored
  3. Restart the server to apply

After Any Certificate Change

All three methods require a server restart before HTTPS uses the new certificate.

If you are running Osprey via Docker, restart the container:

docker restart <osprey-container-name>

Troubleshooting

Symptom Likely Cause Resolution
Status banner shows red error No cert configured or file unreadable Generate or upload a certificate
Browser shows "Not Secure" after upload Server not restarted Restart the Osprey service
Let's Encrypt request fails Port 80 not accessible Check firewall rules; port 80 must be open publicly
Days remaining shown in red Certificate expiring in < 30 days Renew or replace the certificate
Upload fails Mismatched cert/key pair Ensure both files belong to the same key pair