Remote Server Deployment

This guide covers deploying Oscilla on a remote server with HTTPS and process management.

Prerequisites

Node.js 18+ installed
Git access to the Oscilla repository
SSL certificates (e.g., Let's Encrypt)
pm2 for process management

Quick Start

# Clone the repository
git clone git@yourserver:yourrepo/oscilla.git /var/www/oscilla
cd /var/www/oscilla

# Install dependencies
npm install

# Set up SSL certificates (see HTTPS Setup below)
mkdir -p certs
# Copy your certs here...

# Start with pm2
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

HTTPS Setup

HTTPS is required for browser features like microphone recording. See the full guide: HTTPS Server Setup

Quick version:

# Copy Let's Encrypt certs to app directory
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ./certs/
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ./certs/
sudo chown -R $USER:$USER ./certs/
chmod 600 ./certs/privkey.pem

Process Management with pm2

pm2 keeps your server running and restarts it on crashes or reboots.

Install pm2

npm install -g pm2

Ecosystem Configuration

Oscilla includes an ecosystem.config.cjs file for pm2. Example configuration for multiple instances:

module.exports = {
  apps: [
    {
      name: 'whatyouheard',
      script: 'server.js',
      cwd: '/var/www/whatyouheard',
      env: {
        PORT: 3443,
        SSL_CERT_PATH: './certs/fullchain.pem',
        SSL_KEY_PATH: './certs/privkey.pem',
        OSC_LOCAL_PORT: 57121,
        OSC_REMOTE_PORT: 57120
      }
    },
    {
      name: 'polygonfield',
      script: 'server.js',
      cwd: '/var/www/polygonfield',
      env: {
        PORT: 3444,
        SSL_CERT_PATH: './certs/fullchain.pem',
        SSL_KEY_PATH: './certs/privkey.pem',
        OSC_LOCAL_PORT: 57122,
        OSC_REMOTE_PORT: 57123
      }
    }
  ]
};

Configuration Options

Option	Description
`name`	Process name shown in pm2 list
`script`	Entry point (always `server.js`)
`cwd`	Working directory for this instance
`env.PORT`	HTTPS port to listen on
`env.SSL_CERT_PATH`	Path to SSL certificate
`env.SSL_KEY_PATH`	Path to SSL private key
`env.OSC_LOCAL_PORT`	Port for incoming OSC messages
`env.OSC_REMOTE_PORT`	Port for outgoing OSC messages

pm2 Commands

# Start all apps from ecosystem file
pm2 start ecosystem.config.cjs

# Save process list (survives reboot)
pm2 save

# Set up startup script (run on boot)
pm2 startup

# View running processes
pm2 list

# View logs
pm2 logs              # All apps
pm2 logs whatyouheard # Specific app

# Restart after code update
pm2 restart all
pm2 restart whatyouheard

# Stop/delete processes
pm2 stop whatyouheard
pm2 delete whatyouheard
pm2 delete all

Firewall Configuration

Open the ports you're using:

sudo ufw allow 3443
sudo ufw allow 3444

Updating the Server

cd /var/www/whatyouheard
git pull
pm2 restart whatyouheard

Multiple Instances

To run multiple Oscilla projects on the same server:

Clone to separate directories (/var/www/project1, /var/www/project2)
Copy certs to each directory's certs/ folder
Use different ports for each instance (both HTTPS and OSC)
Add each to ecosystem.config.cjs

Troubleshooting

Server won't start with HTTPS

Check cert paths exist: ls -la ./certs/
Check permissions: private key should be readable by Node process
Look for errors: pm2 logs

Port already in use

Check what's using the port: lsof -i :3443
Kill existing process or use a different port

Certificate renewal

After Let's Encrypt renews certs (every 90 days), copy the new certs and restart:

sudo cp /etc/letsencrypt/live/yourdomain.com/*.pem ./certs/
sudo chown $USER:$USER ./certs/*.pem
pm2 restart all

Consider setting up a renewal hook to automate this - see HTTPS Server Setup.

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