Self-Hosting the Web Editor

Deploy your own instance of the HyperPerms web editor for maximum security and control. This guide covers deployment options and configuration.

Why Self-Host?

  • Privacy - Your permission data stays on your infrastructure
  • Security - Full control over access and data storage
  • Customization - Modify the editor to your needs
  • Availability - No dependency on external services
  • Compliance - Meet organizational data residency requirements

Requirements

For Vercel Deployment (Recommended)

  • Vercel account (free tier works)
  • GitHub account (for deployment)
  • Upstash Redis account (for session storage)

For Docker Deployment

  • Docker and Docker Compose
  • Server with at least 512MB RAM
  • Redis instance (local or remote)

For Manual Deployment

  • Node.js 18 or higher
  • Redis instance
  • Web server (nginx, Apache, etc.)

Vercel Deployment

Vercel is the easiest way to deploy the web editor. It provides automatic builds, CDN, and SSL certificates.

Step 1: Set Up Upstash Redis

  1. Create an account at upstash.com
  2. Create a new Redis database
  3. Copy the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN

Step 2: Fork the Repository

  1. Go to the HyperPerms web editor GitHub repository
  2. Click "Fork" to create your own copy

Step 3: Deploy to Vercel

  1. Log in to vercel.com
  2. Click "New Project"
  3. Import your forked repository
  4. Add environment variables (see below)
  5. Click "Deploy"

Environment Variables

text
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token-here
NEXT_PUBLIC_APP_URL=https://your-domain.vercel.app
You can use a custom domain in Vercel for free. Go to your project settings and add your domain under "Domains".

Docker Deployment

Docker provides a consistent deployment environment with easy setup.

Step 1: Clone the Repository

bash
git clone https://github.com/hyperperms/hyperperms-web.git
cd hyperperms-web

Step 2: Configure Environment

Create a .env file:

text
REDIS_URL=redis://localhost:6379
NEXT_PUBLIC_APP_URL=https://editor.yourserver.com
SESSION_SECRET=your-random-secret-key-here

Step 3: Docker Compose Setup

Create docker-compose.yml:

yaml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - REDIS_URL=redis://redis:6379
      - NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL}
      - SESSION_SECRET=${SESSION_SECRET}
    depends_on:
      - redis

  redis:
    image: redis:alpine
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes

volumes:
  redis_data:

Step 4: Build and Run

bash
docker-compose up -d --build

Step 5: Set Up Reverse Proxy

Configure nginx to proxy to the Docker container:

nginx
server {
    listen 443 ssl;
    server_name editor.yourserver.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

Manual Deployment

Step 1: Clone and Build

bash
git clone https://github.com/hyperperms/hyperperms-web.git
cd hyperperms-web
npm install
npm run build

Step 2: Configure Environment

bash
cp .env.example .env
# Edit .env with your settings

Step 3: Run with PM2

bash
npm install -g pm2
pm2 start npm --name "hyperperms-web" -- start
pm2 save

Configuring the Plugin

After deploying, configure your HyperPerms plugin to use your self-hosted instance.

Edit config.json

json
{
  "webEditor": {
    "enabled": true,
    "url": "https://editor.yourserver.com",
    "sessionTimeout": 86400
  }
}

Reload Configuration

text
/hp reload

Test the Connection

text
/hp editor

# Should show your custom URL:
[HyperPerms] Click to open: https://editor.yourserver.com/abc123xyz

Environment Variables Reference

VariableDescriptionRequired
REDIS_URLRedis connection URLYes*
UPSTASH_REDIS_REST_URLUpstash Redis REST URLYes*
UPSTASH_REDIS_REST_TOKENUpstash Redis REST tokenYes*
NEXT_PUBLIC_APP_URLPublic URL of your editorYes
SESSION_SECRETSecret for session encryptionRecommended

* Use either REDIS_URL or the UPSTASH_* variables, depending on your Redis provider.

Security Considerations

Always use HTTPS for your self-hosted editor. Permission data should never be transmitted over unencrypted connections.

Recommendations

  • Use HTTPS - Get certificates from Let's Encrypt or your provider
  • Firewall Redis - Never expose Redis to the public internet
  • Rotate secrets - Change SESSION_SECRET periodically
  • Monitor access - Keep logs of editor sessions
  • Regular updates - Pull updates from the main repository

Updating

Vercel

Pull changes from the upstream repository to your fork. Vercel will automatically rebuild and deploy.

Docker

bash
git pull origin main
docker-compose up -d --build

Manual

bash
git pull origin main
npm install
npm run build
pm2 restart hyperperms-web

Troubleshooting

Redis Connection Failed

  • Verify Redis is running and accessible
  • Check the connection URL format
  • Ensure firewall allows the connection

Sessions Not Persisting

  • Check Redis connectivity
  • Verify environment variables are set correctly
  • Check application logs for errors

Plugin Can't Connect

  • Verify the URL in config.json matches your deployment
  • Check SSL certificate validity
  • Ensure the server allows incoming connections

See Also