shelter-plugins/docs/NGINX-STATIC-HOSTING.md

# Hosting Shelter Plugins with NGINX

This guide walks you through hosting the built plugin files using NGINX on your own server.

## Prerequisites

- A server running NGINX
- Access to the server via SSH
- Basic familiarity with Linux command line

## Step 1: Prepare the Plugin Files

First, build the plugins and static site using Lune:

```bash
# Install pnpm if you haven't already
npm install -g pnpm

# Install dependencies
pnpm install

# Build plugins and generate static website
pnpm lune ssg ci
```

The `dist/` directory contains:

```
dist/
├── index.html              # Plugin listing page
├── styles.css              # Shared stylesheet
└── gpt-unslothed/
    ├── index.html          # Plugin documentation page
    ├── plugin.js           # Bundled plugin code
    └── plugin.json         # Plugin manifest
```

Lune SSG (Static Site Generator) produces:
- `index.html` — a listing page for all plugins in your monorepo
- `<plugin-name>/index.html` — individual documentation pages for each plugin
- `plugin.js` — the bundled plugin code (all JSX/JS sources bundled into a single file)
- `plugin.json` — the plugin manifest
- `styles.css` — the shared stylesheet

**Note:** To build only the plugin bundles (without the static website), run `pnpm lune ci` instead.

## Step 2: Set Up the Web Directory

Create a directory for the static files:

```bash
# Create the directory (you can change the path as needed)
sudo mkdir -p /var/www/shelter-plugins

# Copy the built files
sudo cp -r dist/* /var/www/shelter-plugins/
```

## Step 3: Configure NGINX

Create a new NGINX configuration file:

```bash
sudo nano /etc/nginx/sites-available/shelter-plugins
```

Add the following configuration:

```nginx
server {
    listen 80;
    server_name plugins.your-domain.com;  # Change to your domain

    root /var/www/shelter-plugins;
    index index.html;

    # Serve plugin directories (each plugin has its own page and files)
    location /gpt-unslothed {
        try_files $uri $uri/ =404;
    }

    # Catch-all for 404
    location = /404.html {
        internal;
    }

    # Redirect all other requests to 404
    location / {
        return 404;
    }
}
```

### Configuration Notes

- Change `plugins.your-domain.com` to your actual domain or IP address
- The `try_files` directive lets NGINX auto-detect the correct MIME type for each file (HTML, CSS, JS, JSON)
- Each plugin directory is served from its own URL path (e.g., `http://plugins.your-domain.com/gpt-unslothed/`)

## Step 4: Enable the Site

```bash
# Enable the site
sudo ln -s /etc/nginx/sites-available/shelter-plugins /etc/nginx/sites-enabled/

# Test the configuration
sudo nginx -t

# Reload NGINX
sudo systemctl reload nginx
```

## Step 5: Use in Shelter

### Installing plugins

In Shelter, add the plugin using the plugin manifest URL:

```
http://plugins.your-domain.com/gpt-unslothed/plugin.json
```

Or if using HTTPS (recommended):

```
https://plugins.your-domain.com/gpt-unslothed/plugin.json
```

### Viewing the plugin page

Visiting the plugin directory URL serves the documentation page:

```
http://plugins.your-domain.com/gpt-unslothed/
```

This displays the SSG-generated plugin page with a copy-to-clipboard button for the plugin URL.

### Viewing the index page

The main plugin listing page is served at:

```
http://plugins.your-domain.com/
```

## Optional: Set Up HTTPS with Let's Encrypt

Install Certbot and get an SSL certificate:

```bash
# Install Certbot (Ubuntu/Debian)
sudo apt update
sudo apt install certbot python3-certbot-nginx

# Get the certificate
sudo certbot --nginx -d plugins.your-domain.com
```

Certbot will automatically update your NGINX configuration to use HTTPS.

## Automation: Deploying Updates

To make updates easier, you can create a simple deployment script:

```bash
#!/bin/bash
# deploy.sh

set -e

# Build plugins and static website
echo "Building plugins and static website..."
pnpm lune ssg ci

# Copy files
echo "Copying files to web directory..."
sudo rsync -av --delete dist/ /var/www/shelter-plugins/

# Reload NGINX (optional)
# sudo systemctl reload nginx

echo "Deployment complete!"
```

Make it executable and run it when you want to deploy:

```bash
chmod +x deploy.sh
./deploy.sh
```

## Server File Structure

After deployment, your server should look like this:

```
/var/www/shelter-plugins/
├── index.html
├── styles.css
└── gpt-unslothed/
    ├── index.html
    ├── plugin.js
    └── plugin.json
```

## Troubleshooting

### 404 Not Found

- Ensure the `dist/` directory contents were copied correctly
- Check that your NGINX site is enabled: `ls /etc/nginx/sites-enabled/`
- Check NGINX error logs: `sudo tail -f /var/log/nginx/error.log`

### Plugin not loading in Shelter

- Make sure the URL points to `plugin.json`, not the directory
- Check browser console for CORS errors (may need to add CORS headers)

### Adding CORS headers

If Shelter is experiencing CORS issues, add these headers to your NGINX config:

```nginx
location / {
    add_header 'Access-Control-Allow-Origin' '*';
    add_header 'Access-Control-Allow-Methods' 'GET, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Content-Type';
    
    if ($request_method = 'OPTIONS') {
        return 204;
    }
}
```