152 lines
3.8 KiB
Markdown
152 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```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
|
|
|
|
If you need to set environment variables, edit the `env` section in `ecosystem.config.cjs` or create a `.env` file in `/floter-design`.
|
|
|