7.6 KiB
7.6 KiB
Deployment Guide — ETC PRS Viewer & Editor
This guide covers deploying the app to a Digital Ocean Droplet running Ubuntu 24.04.
Prerequisites
- A Digital Ocean Droplet (1 GB RAM minimum, 2 GB recommended)
- A domain name pointed at your droplet's IP
- SSH access to the droplet
1. Initial Server Setup
# Update packages
sudo apt update && sudo apt upgrade -y
# Install Node.js 20 (LTS)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Verify
node --version # should be v20.x
npm --version
# Install build tools (needed for better-sqlite3)
sudo apt install -y build-essential python3
# Install PM2 globally
sudo npm install -g pm2
# Install Nginx
sudo apt install -y nginx
# Install Certbot for SSL
sudo apt install -y certbot python3-certbot-nginx
2. Create the App User and Directories
# Create a dedicated user for the app (no login shell)
sudo useradd --system --shell /bin/false --home /opt/etc-prs prs
# Create app directory
sudo mkdir -p /opt/etc-prs/app
sudo chown -R prs:prs /opt/etc-prs
# Create data directory for SQLite (outside the app, survives redeployment)
sudo mkdir -p /var/lib/etc-prs
sudo chown -R prs:prs /var/lib/etc-prs
# Create log directory
sudo mkdir -p /var/log/etc-prs
sudo chown -R prs:prs /var/log/etc-prs
3. Deploy the Application
# Clone or copy your project to the server
# Option A: Git
cd /opt/etc-prs
sudo -u prs git clone https://github.com/yourusername/etc-prs-ui.git app
# Option B: Copy files via scp from your local machine
# scp -r ./etc-prs-ui user@your-droplet-ip:/tmp/
# sudo mv /tmp/etc-prs-ui /opt/etc-prs/app
# sudo chown -R prs:prs /opt/etc-prs/app
cd /opt/etc-prs/app
# Install dependencies (as the prs user)
sudo -u prs npm install
# Build the app
sudo -u prs npm run build
4. Environment Configuration
# Create the production .env file
sudo -u prs nano /opt/etc-prs/app/.env
Add the following contents:
DATABASE_URL=/var/lib/etc-prs/personalities.db
RATE_LIMIT_PUBLISH=5
RATE_LIMIT_READ=100
PUBLIC_BASE_URL=https://yourdomain.com
Replace yourdomain.com with your actual domain.
5. Configure PM2
Create the PM2 ecosystem file:
sudo -u prs nano /opt/etc-prs/app/ecosystem.config.cjs
module.exports = {
apps: [{
name: 'etc-prs',
script: '/opt/etc-prs/app/build/index.js',
cwd: '/opt/etc-prs/app',
user: 'prs',
env: {
NODE_ENV: 'production',
PORT: '3000',
HOST: '127.0.0.1',
},
error_file: '/var/log/etc-prs/error.log',
out_file: '/var/log/etc-prs/out.log',
log_date_format: 'YYYY-MM-DD HH:mm:ss',
restart_delay: 3000,
max_restarts: 10,
}]
};
Start the app with PM2:
# Start
sudo -u prs pm2 start /opt/etc-prs/app/ecosystem.config.cjs
# Save the process list so PM2 restores it on reboot
sudo -u prs pm2 save
# Set PM2 to start on system boot
sudo pm2 startup systemd -u prs --hp /opt/etc-prs
# Run the command PM2 outputs
Verify the app is running:
sudo -u prs pm2 status
# Should show etc-prs as "online"
# Check logs
sudo -u prs pm2 logs etc-prs --lines 50
6. Configure Nginx
sudo nano /etc/nginx/sites-available/etc-prs
server {
listen 80;
server_name yourdomain.com www.yourdomain.com;
# Gzip
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
# Security headers
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "strict-origin-when-cross-origin";
# Proxy to SvelteKit
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
# Increase timeout for large uploads
proxy_read_timeout 30s;
client_max_body_size 2M;
}
}
Enable and test:
sudo ln -s /etc/nginx/sites-available/etc-prs /etc/nginx/sites-enabled/
sudo nginx -t # should say "syntax is ok"
sudo systemctl reload nginx
7. SSL with Let's Encrypt
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
Follow the prompts. Certbot will automatically modify your Nginx config to add HTTPS and set up auto-renewal.
Verify auto-renewal works:
sudo certbot renew --dry-run
8. Database Backups
Set up a nightly cron job to back up the SQLite database:
sudo mkdir -p /var/backups/etc-prs
# Create backup script
sudo nano /opt/etc-prs/backup.sh
#!/bin/bash
DATE=$(date +%Y-%m-%d)
BACKUP_DIR=/var/backups/etc-prs
DB_PATH=/var/lib/etc-prs/personalities.db
# Create backup using SQLite's online backup
sqlite3 "$DB_PATH" ".backup $BACKUP_DIR/personalities-$DATE.db"
# Keep only the last 30 days of backups
find "$BACKUP_DIR" -name "personalities-*.db" -mtime +30 -delete
echo "Backup completed: personalities-$DATE.db"
sudo chmod +x /opt/etc-prs/backup.sh
# Add to cron (runs at 2am daily)
sudo crontab -e
Add this line:
0 2 * * * /opt/etc-prs/backup.sh >> /var/log/etc-prs/backup.log 2>&1
9. Redeployment
When you push updates:
cd /opt/etc-prs/app
# Pull latest code
sudo -u prs git pull
# Install any new dependencies
sudo -u prs npm install
# Rebuild
sudo -u prs npm run build
# Restart the app (zero-downtime reload)
sudo -u prs pm2 reload etc-prs
The SQLite database at /var/lib/etc-prs/personalities.db is never touched by redeployment since it lives outside the app directory.
10. Useful Commands
# View live logs
sudo -u prs pm2 logs etc-prs
# Restart app
sudo -u prs pm2 restart etc-prs
# Stop app
sudo -u prs pm2 stop etc-prs
# Check Nginx status
sudo systemctl status nginx
# View Nginx error log
sudo tail -f /var/log/nginx/error.log
# Open SQLite database directly
sqlite3 /var/lib/etc-prs/personalities.db
# Example queries
sqlite3 /var/lib/etc-prs/personalities.db "SELECT id, name, manufacturer, channel_count, created_at FROM personalities ORDER BY created_at DESC LIMIT 20;"
sqlite3 /var/lib/etc-prs/personalities.db "SELECT COUNT(*) FROM personalities;"
# Delete a personality by ID (if you need to moderate)
sqlite3 /var/lib/etc-prs/personalities.db "DELETE FROM personalities WHERE id = 'the_id_here';"
11. Firewall
# Allow SSH, HTTP, and HTTPS
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status
12. Creating Admin Users
Admins are managed via a CLI script — there is no self-registration UI.
# Create your first admin (run from the app directory on the server)
cd /opt/etc-prs/app
node scripts/create-admin.js your-username your-password
# To update an existing admin's password (same command — it upserts)
node scripts/create-admin.js your-username new-password
# To add another admin
node scripts/create-admin.js another-user their-password
Requirements:
- Username: 2–32 characters
- Password: minimum 8 characters (use something strong)
The admin panel is available at https://yourdomain.com/admin.
Local Development
# Install dependencies
npm install
# Start dev server (uses ./dev.db automatically)
npm run dev
# The app runs at http://localhost:5173
# SQLite database is created at ./dev.db on first run