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 locally using Lune:

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

# Install dependencies
pnpm install

# Build the plugins
pnpm lune ci

This creates the built plugin files in the dist/ directory (e.g., dist/gpt/plugin.js, dist/gpt/plugin.json).

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 files
    location /gpt-unslothed {
        default_type application/json;
        try_files $uri $uri/ =404;
    }

    # Serve preview images
    location /previews {
        default_type image/png;
        try_files $uri $uri/ =404;
    }

    # Serve README
    location /README.md {
        default_type text/markdown;
        try_files $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 default_type application/json ensures browsers don't try to execute the plugin files
• The configuration serves plugins from paths like 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

In Shelter, add the plugin using the URL:

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

Or if using HTTPS (recommended):

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

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
echo "Building plugins..."
pnpm lune 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

File Structure

After deployment, your server should look like this:

/var/www/shelter-plugins/
├── gpt-unslothed/
│   ├── plugin.json
│   ├── index.jsx
│   └── settings.jsx
└── previews/
    └── gpt.png

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;
    }
    
    default_type application/json;
    try_files $uri $uri/ =404;
}