floter.design/DEPLOYMENT.md

# Deployment Guide for Hetzner VPS

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

---

## Docker deployment (recommended)

Config is in git; defaults use port **3001**. Minimal steps on the server:

### Prerequisites on server

- Docker and Docker Compose installed

### Deploy / update

```bash
cd /path/to/floter-design   # e.g. ~/floter-design
git pull
docker-compose up -d --build
```

### Optional: custom port

Create a `.env` file (do not commit) and set:

```bash
PORT=3001
```

Then run `docker-compose up -d --build` as above.

### Useful commands

- Logs: `docker-compose logs -f floter-design`
- Restart: `docker-compose restart floter-design`
- Stop: `docker-compose down`

Nginx in front of the app should proxy to `http://127.0.0.1:3001` (or the port in your `.env`).

---

## PM2 deployment (without Docker)

### 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:

```bash
cd /floter-design
npm install
npm run build
```

### 2. Create Logs Directory (for PM2)

```bash
mkdir -p /floter-design/logs
```

### 3. Start the Application with PM2

```bash
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:
   ```bash
   sudo cp nginx.conf.example /etc/nginx/sites-available/floter-design
   ```

2. Edit the configuration:
   ```bash
   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:
   ```bash
   sudo ln -s /etc/nginx/sites-available/floter-design /etc/nginx/sites-enabled/
   ```

4. Test nginx configuration:
   ```bash
   sudo nginx -t
   ```

5. Reload nginx:
   ```bash
   sudo systemctl reload nginx
   ```

### 5. Set Up SSL (Optional but Recommended)

If you want HTTPS, use Let's Encrypt:

```bash
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:**
   ```bash
   pm2 list
   ```
   If `floter-design` is not running or shows as `errored`, check logs:
   ```bash
   pm2 logs floter-design --lines 50
   ```

2. **Test if Node.js server responds:**
   ```bash
   curl http://localhost:3001
   ```
   If this fails, the Node.js server isn't running.

3. **Check if port 3001 is in use:**
   ```bash
   sudo netstat -tlnp | grep 3001
   # or
   sudo ss -tlnp | grep 3001
   ```

4. **Try running the server directly to see errors:**
   ```bash
   cd ~/floter-design
   node build/index.js
   ```
   This will show any startup errors.

5. **Rebuild and restart:**
   ```bash
   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

### Important: VITE_PUBLIC_* Variables

Variables prefixed with `VITE_PUBLIC_` (like `VITE_PUBLIC_CLOUDINARY_CLOUD_NAME`) must be available **at build time**, not just runtime. They are embedded in the client bundle during `npm run build`.

### Setting Up Environment Variables

**1. Create a `.env` file in your project directory:**

```bash
cd ~/floter-design
nano .env
```

Add your environment variables:
```bash
# Cloudinary Configuration (required)
VITE_PUBLIC_CLOUDINARY_CLOUD_NAME=your-actual-cloud-name

# Add any other VITE_PUBLIC_* variables you need
```

**2. Build with environment variables:**

The `.env` file will be automatically loaded when you run:
```bash
npm run build
```

**3. For runtime-only environment variables** (not prefixed with `VITE_PUBLIC_`):

Edit `ecosystem.config.cjs` and add them to the `env` section:
```javascript
env: {
  NODE_ENV: 'production',
  PORT: 3001,
  HOST: '0.0.0.0',
  // Add other runtime variables here
}
```

**4. After updating `.env`, rebuild and restart:**

```bash
npm run build
pm2 restart floter-design
```

**5. Security Note:**

- Never commit `.env` files to git (already in `.gitignore`)
- The `.env` file should contain your actual secrets
- `VITE_PUBLIC_*` variables are exposed to the client-side code - don't put secrets there