HTTPS Server Setup

This guide explains how to run the Oscilla server with HTTPS, which is required for certain browser features like microphone access (audio recording).

Why HTTPS?

Browsers require a secure context (HTTPS) for:

• getUserMedia() - microphone/camera access for audio recording
• Service Workers
• Certain Web APIs

Without HTTPS, the recording button in the Audio Object Editor will be disabled on remote servers.

Quick Setup with Let's Encrypt

1. Copy certificates to the app directory

# Create certs folder
mkdir -p /path/to/oscilla/certs

# Copy Let's Encrypt certs (adjust domain)
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem /path/to/oscilla/certs/
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem /path/to/oscilla/certs/

# Set ownership and permissions
sudo chown -R $USER:$USER /path/to/oscilla/certs/
chmod 600 /path/to/oscilla/certs/privkey.pem

2. Run with HTTPS

# Using port 443 (requires sudo)
sudo node server.js --port 443 \
  --ssl-cert ./certs/fullchain.pem \
  --ssl-key ./certs/privkey.pem

# Or use a high port (no sudo needed, but must open in firewall)
node server.js --port 3443 \
  --ssl-cert ./certs/fullchain.pem \
  --ssl-key ./certs/privkey.pem

3. Open firewall port (if using high port)

sudo ufw allow 3443

Access via https://yourdomain.com:3443/

Configuration Options

SSL can be configured via CLI arguments or environment variables:

Environment Variables Example

export SSL_CERT_PATH=/path/to/fullchain.pem
export SSL_KEY_PATH=/path/to/privkey.pem
node server.js --port 3443

Certificate Renewal

Let's Encrypt certificates expire every 90 days. After renewal, copy the new certs:

sudo cp /etc/letsencrypt/live/yourdomain.com/*.pem /path/to/oscilla/certs/
sudo chown $USER:$USER /path/to/oscilla/certs/*.pem

Or set up a renewal hook in /etc/letsencrypt/renewal-hooks/deploy/oscilla.sh:

#!/bin/bash
cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem /path/to/oscilla/certs/
cp /etc/letsencrypt/live/yourdomain.com/privkey.pem /path/to/oscilla/certs/
chown youruser:youruser /path/to/oscilla/certs/*.pem
# Optionally restart the server
systemctl restart oscilla

WebSocket over HTTPS

When the page is served over HTTPS, WebSocket connections automatically use wss:// (WebSocket Secure). This is handled automatically in socket.js.

Troubleshooting

"SSL certs specified but not found"

• Check that the cert paths are correct and files exist
• Verify file permissions (the Node process must be able to read them)

ERR_SSL_PROTOCOL_ERROR

• Server may not be starting in HTTPS mode - check console output for "HTTPS enabled"
• Verify cert files are valid PEM format

Mixed Content / WebSocket blocked

• Ensure the page is accessed via HTTPS (not HTTP)
• The WebSocket will automatically use wss:// when page is HTTPS

Alternative: Apache Reverse Proxy

If you already have Apache handling SSL on port 443, you can proxy to the HTTP Express server. This is more complex but avoids managing certs in the app. See Apache documentation for ProxyPass configuration with WebSocket support.

Tip: use ← → or ↑ ↓ to navigate the docs