floter.design/DEPLOYMENT.md

Deployment Guide for Hetzner VPS

This guide will help you deploy your SvelteKit application on your Hetzner VPS.

Prerequisites

• Node.js installed on your VPS
• PM2 installed globally (npm install -g pm2)
• Nginx installed and running

Deployment Steps

1. Build the Application

On your VPS, navigate to your project directory:

cd /floter-design
npm install
npm run build

2. Create Logs Directory (for PM2)

mkdir -p /floter-design/logs

3. Start the Application with PM2

cd /floter-design
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

The last command (pm2 startup) will give you a command to run with sudo to enable PM2 to start on system boot.

4. Configure Nginx

1. Copy the nginx configuration:

   sudo cp nginx.conf.example /etc/nginx/sites-available/floter-design
   

2. Edit the configuration:

   sudo nano /etc/nginx/sites-available/floter-design
   

   If using IP address (no domain yet): The config already has server_name _; which will work for IP access. You can optionally replace _ with your actual IP address.

   If using a domain: Comment out the IP-based server block and uncomment the domain-based one, then replace your-domain.com with your actual domain name.

3. Enable the site:

   sudo ln -s /etc/nginx/sites-available/floter-design /etc/nginx/sites-enabled/
   

4. Test nginx configuration:

   sudo nginx -t
   

5. Reload nginx:

   sudo systemctl reload nginx
   

5. Set Up SSL (Optional but Recommended)

If you want HTTPS, use Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

Then uncomment the HTTPS server block in your nginx config and reload.

Useful Commands

PM2 Commands

• View running apps: pm2 list
• View logs: pm2 logs floter-design
• Restart app: pm2 restart floter-design
• Stop app: pm2 stop floter-design
• Monitor: pm2 monit

Nginx Commands

• Test config: sudo nginx -t
• Reload: sudo systemctl reload nginx
• Restart: sudo systemctl restart nginx
• Status: sudo systemctl status nginx

Troubleshooting

ERR_CONNECTION_REFUSED Errors

If you see ERR_CONNECTION_REFUSED errors for /_app/immutable/ assets:

1. Check if PM2 is running:

   pm2 list
   

   If floter-design is not running or shows as errored, check logs:

   pm2 logs floter-design --lines 50
   

2. Test if Node.js server responds:

   curl http://localhost:3001
   

   If this fails, the Node.js server isn't running.

3. Check if port 3001 is in use:

   sudo netstat -tlnp | grep 3001
   # or
   sudo ss -tlnp | grep 3001
   

4. Try running the server directly to see errors:

   cd ~/floter-design
   node build/index.js
   

   This will show any startup errors.

5. Rebuild and restart:

   cd ~/floter-design
   npm run build
   pm2 restart floter-design
   

Other Common Issues

• Port already in use: Change the PORT in ecosystem.config.cjs (default is 3001) or stop the process using that port
• Port 3001 conflicts: You can use any available port (3002, 3003, etc.) - just update both ecosystem.config.cjs and your nginx config
• 502 Bad Gateway: Check if the Node.js server is running (pm2 list) and check logs (pm2 logs)
• Permission errors: Make sure the user running PM2 has proper permissions to the ~/floter-design directory
• Missing dependencies: Run npm install in ~/floter-design before building

Environment Variables

If you need to set environment variables, edit the env section in ecosystem.config.cjs or create a .env file in /floter-design.