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:

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

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

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

Add the following configuration:

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

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

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

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

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:

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;
    }
}