IIS Deployment Guide - HyperSpin Docs with Built-in Editor

This guide explains how to deploy the HyperSpin documentation with the built-in editor to IIS (Internet Information Services).

Architecture Overview

Your deployment consists of two parts:

Static Documentation Site (Docusaurus) - Runs on IIS as static files
Backend API Server (Node.js/Express) - Runs as a separate process, proxied through IIS

Prerequisites

Windows Server with IIS installed
Node.js installed (v18 or higher)
URL Rewrite module for IIS (download here)
Application Request Routing (ARR) for IIS (download here)
Git (for deployment)

Part 1: Deploy Static Documentation Site

Step 1: Build the Documentation

On your development machine or build server:

cd E:\dev\HyperSpin-Docs
npm install
npm run build

This creates a build/ directory with static files.

Step 2: Copy to IIS

Copy the contents of the build/ directory to your IIS website folder:

# Example: Copy to IIS default website
xcopy /E /I /Y E:\dev\HyperSpin-Docs\build C:\inetpub\wwwroot\hyperspin-docs

Step 3: Configure IIS Website

Open IIS Manager
Create New Website (or use existing):
- Site name: HyperSpin-Docs
- Physical path: C:\inetpub\wwwroot\hyperspin-docs
- Binding:
  - Type: HTTP or HTTPS
  - IP: All Unassigned
  - Port: 80 (or 443 for HTTPS)
  - Host name: docs.hyperspin-fe.com (or your domain)
Set Default Document:
- Click on website → Default Document
- Add index.html if not present

Step 4: Configure URL Rewrite for SPA Routing

Docusaurus is a Single Page Application (SPA) and needs URL rewriting:

Click on your website in IIS Manager
Double-click URL Rewrite
Click Add Rule(s) → Blank Rule
Configure:
- Name: Docusaurus SPA Routing
- Pattern: ^(.*)$
- Conditions:
  - Click Add
  - Condition input: {REQUEST_FILENAME}
  - Check if input string: Is Not a File
  - Click Add again
  - Condition input: {REQUEST_FILENAME}
  - Check if input string: Is Not a Directory
- Action:
  - Action type: Rewrite
  - Rewrite URL: index.html

Or manually edit web.config in the site root:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Docusaurus SPA Routing" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
            <add input="{REQUEST_URI}" pattern="^/api/" negate="true" />
          </conditions>
          <action type="Rewrite" url="index.html" />
        </rule>
      </rules>
    </rewrite>
    <staticContent>
      <mimeMap fileExtension=".json" mimeType="application/json" />
      <mimeMap fileExtension=".woff" mimeType="application/font-woff" />
      <mimeMap fileExtension=".woff2" mimeType="application/font-woff2" />
    </staticContent>
  </system.webServer>
</configuration>

Part 2: Deploy Backend API Server

Step 1: Copy API Files to Server

Copy the api/ directory to your server:

# Example location
xcopy /E /I /Y E:\dev\HyperSpin-Docs\api C:\inetpub\hyperspin-docs-api

Step 2: Install Dependencies

On the server:

cd C:\inetpub\hyperspin-docs-api
npm install --production

Step 3: Create Environment Configuration

Create C:\inetpub\hyperspin-docs-api\.env:

# GitHub Configuration
GITHUB_TOKEN=ghp_your_github_personal_access_token_here
GITHUB_OWNER=HyperSpin-LLC
GITHUB_REPO=HyperSpin-Docs
GITHUB_DEFAULT_BRANCH=main

# API Configuration
API_PORT=3001
API_AUTH_TOKEN=your_secure_api_token_here

# CORS Configuration - Add your domain
ALLOWED_ORIGINS=https://docs.hyperspin-fe.com,http://localhost:3000

# Optional: Node Environment
NODE_ENV=production

Security Note: Keep this .env file secure! It contains sensitive credentials.

Step 4: Run API Server as Windows Service

Use PM2 or node-windows to run the API as a Windows service:

Option A: Using PM2 (Recommended)

# Install PM2 globally
npm install -g pm2
npm install -g pm2-windows-service

# Setup PM2 as Windows service
pm2-service-install

# Start API server
cd C:\inetpub\hyperspin-docs-api
pm2 start server.js --name hyperspin-docs-api
pm2 save

# Configure to start on boot
pm2 startup

Option B: Using node-windows

Create a service installer script install-service.js:

const Service = require('node-windows').Service;

const svc = new Service({
  name: 'HyperSpin Docs API',
  description: 'Backend API for HyperSpin documentation editor',
  script: 'C:\\inetpub\\hyperspin-docs-api\\server.js',
  nodeOptions: ['--max_old_space_size=4096'],
  env: [{
    name: "NODE_ENV",
    value: "production"
  }]
});

svc.on('install', () => {
  console.log('Service installed. Starting...');
  svc.start();
});

svc.on('start', () => {
  console.log('Service started successfully!');
});

svc.install();

Install the service:

npm install -g node-windows
cd C:\inetpub\hyperspin-docs-api
node install-service.js

Step 5: Configure IIS as Reverse Proxy

Configure IIS to proxy /api/* requests to the Node.js API server:

Enable Proxy in ARR:
- Open IIS Manager
- Click server name (root level)
- Double-click Application Request Routing Cache
- Click Server Proxy Settings (right panel)
- Check Enable proxy
- Click Apply
Add Reverse Proxy Rule:
- Go to your website (HyperSpin-Docs)
- Double-click URL Rewrite
- Click Add Rule(s) → Reverse Proxy
- If prompted to enable proxy, click OK
- Configure:
  - Inbound Rules:
    - Server name: localhost:3001
    - Enable SSL Offloading: Check if using HTTPS
  - Outbound Rules: (leave default)
Or manually add to web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <!-- API Reverse Proxy - Process FIRST -->
        <rule name="API Reverse Proxy" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="http://localhost:3001/api/{R:1}" />
          <serverVariables>
            <set name="HTTP_X_ORIGINAL_HOST" value="{HTTP_HOST}" />
          </serverVariables>
        </rule>

        <!-- Docusaurus SPA Routing - Process SECOND -->
        <rule name="Docusaurus SPA Routing" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
            <add input="{REQUEST_URI}" pattern="^/api/" negate="true" />
          </conditions>
          <action type="Rewrite" url="index.html" />
        </rule>
      </rules>
    </rewrite>
    <staticContent>
      <mimeMap fileExtension=".json" mimeType="application/json" />
      <mimeMap fileExtension=".woff" mimeType="application/font-woff" />
      <mimeMap fileExtension=".woff2" mimeType="application/font-woff2" />
    </staticContent>
  </system.webServer>
</configuration>

Part 3: Testing the Deployment

Test Static Site

Open browser to http://docs.hyperspin-fe.com (or your domain)
Verify documentation loads correctly
Navigate between pages
Check that direct URLs work (e.g., /docs/plugins/intro)

Test API Server

# Test health endpoint
curl http://localhost:3001/api/health

# Should return:
# {"status":"ok","service":"HyperSpin Docs API","timestamp":"..."}

Test Reverse Proxy

# Test through IIS proxy
curl http://docs.hyperspin-fe.com/api/health

# Should return same as above

Test Editor

Visit any documentation page
Click "Edit this page" button
Login modal should appear
Enter credentials to test authentication
Editor should open with file content

Part 4: SSL/HTTPS Configuration (Recommended)

Install SSL Certificate

Obtain SSL Certificate:
- Use Let's Encrypt (free)
- Use your domain provider
- Use internal CA for intranet
Install in IIS:
- Open IIS Manager
- Click server name
- Double-click Server Certificates
- Import certificate (right panel)
Add HTTPS Binding:
- Go to your website
- Click Bindings (right panel)
- Click Add
- Type: HTTPS
- Port: 443
- SSL Certificate: Select your certificate
Redirect HTTP to HTTPS: Add to web.config:

<rule name="Redirect to HTTPS" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
    <add input="{HTTPS}" pattern="off" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
</rule>

Update CORS Origins

Update C:\inetpub\hyperspin-docs-api\.env:

ALLOWED_ORIGINS=https://docs.hyperspin-fe.com

Restart the API service:

pm2 restart hyperspin-docs-api

Part 5: Continuous Deployment

Option A: Manual Deployment Script

Create deploy.ps1:

# HyperSpin Docs Deployment Script

$ErrorActionPreference = "Stop"

Write-Host "Starting deployment..." -ForegroundColor Green

# 1. Pull latest changes
Write-Host "Pulling latest changes from Git..." -ForegroundColor Yellow
cd E:\dev\HyperSpin-Docs
git pull origin main

# 2. Install dependencies and build
Write-Host "Building documentation..." -ForegroundColor Yellow
npm install
npm run build

# 3. Stop IIS site
Write-Host "Stopping IIS website..." -ForegroundColor Yellow
Stop-WebSite -Name "HyperSpin-Docs"

# 4. Copy files
Write-Host "Copying files to IIS..." -ForegroundColor Yellow
Remove-Item C:\inetpub\wwwroot\hyperspin-docs\* -Recurse -Force
Copy-Item E:\dev\HyperSpin-Docs\build\* C:\inetpub\wwwroot\hyperspin-docs\ -Recurse -Force

# 5. Copy API files (if changed)
Write-Host "Updating API server..." -ForegroundColor Yellow
Copy-Item E:\dev\HyperSpin-Docs\api\* C:\inetpub\hyperspin-docs-api\ -Exclude node_modules,package-lock.json,.env -Recurse -Force

# 6. Install API dependencies
cd C:\inetpub\hyperspin-docs-api
npm install --production

# 7. Restart services
Write-Host "Restarting services..." -ForegroundColor Yellow
pm2 restart hyperspin-docs-api
Start-WebSite -Name "HyperSpin-Docs"

Write-Host "Deployment complete!" -ForegroundColor Green

Run: powershell -ExecutionPolicy Bypass -File deploy.ps1

Option B: Git Webhook Deployment

Set up automatic deployment on git push using:

GitHub Actions
GitLab CI/CD
Azure DevOps Pipelines
Jenkins

Troubleshooting

Static Site Issues

Problem: 404 errors on navigation

Solution: Check URL Rewrite rules are configured
Verify web.config exists in site root

Problem: CSS/JS not loading

Solution: Check MIME types in IIS
Verify file permissions

API Server Issues

Problem: API not responding

Solution: Check if service is running: pm2 status
Check API logs: pm2 logs hyperspin-docs-api
Verify port 3001 is not blocked by firewall

Problem: CORS errors in browser console

Solution: Update ALLOWED_ORIGINS in .env
Restart API service
Clear browser cache

Problem: GitHub operations failing

Solution: Check GITHUB_TOKEN is valid
Verify token has repo scope
Check GitHub API rate limits

Reverse Proxy Issues

Problem: /api/* requests return 404

Solution: Verify ARR is installed and enabled
Check proxy rule order (API rule must be first)
Test direct connection to localhost:3001/api/health

Problem: Infinite redirects

Solution: Check HTTPS redirect rule doesn't conflict with proxy rules
Verify rule order in web.config

Authentication Issues

Problem: Can't log in

Solution: Verify API is reachable at https://api.hyperai.io
Check browser console for CORS errors
Test with curl: curl -X POST https://api.hyperai.io/User/Authenticate -H "Content-Type: application/json" -d '{"userName":"test","password":"test"}'

Security Checklist

HTTPS configured with valid SSL certificate
.env file has secure permissions (not world-readable)
GitHub token has minimum required permissions
API authentication token is strong and random
CORS origins restricted to your domain only
Windows Firewall configured (only ports 80/443 open externally)
Regular backups configured
Monitoring/logging enabled

Monitoring

Check Service Status

# Check API service
pm2 status
pm2 logs hyperspin-docs-api

# Check IIS site
Get-WebSite | Where-Object {$_.Name -eq "HyperSpin-Docs"}

Check Logs

IIS Logs: C:\inetpub\logs\LogFiles
API Logs: pm2 logs hyperspin-docs-api
Windows Event Viewer: Application and System logs

Set Up Alerts

Use Windows Task Scheduler or monitoring tools to:

Alert if API service stops
Alert if IIS site stops
Monitor disk space
Monitor API response times

Backup Strategy

Regular Backups

Configuration:
- web.config
- C:\inetpub\hyperspin-docs-api\.env
Code (if making local changes):
- Entire C:\inetpub\wwwroot\hyperspin-docs directory
- Entire C:\inetpub\hyperspin-docs-api directory

Automated Backups:

# Backup script
$backupPath = "D:\Backups\hyperspin-docs-$(Get-Date -Format 'yyyy-MM-dd')"
New-Item -Path $backupPath -ItemType Directory
Copy-Item C:\inetpub\wwwroot\hyperspin-docs $backupPath\website -Recurse
Copy-Item C:\inetpub\hyperspin-docs-api $backupPath\api -Recurse -Exclude node_modules

Performance Optimization

Enable Compression

Add to web.config:

<system.webServer>
  <urlCompression doStaticCompression="true" doDynamicCompression="true" />
  <httpCompression>
    <staticTypes>
      <add mimeType="text/*" enabled="true" />
      <add mimeType="application/javascript" enabled="true" />
      <add mimeType="application/json" enabled="true" />
    </staticTypes>
  </httpCompression>
</system.webServer>

Enable Caching

Add to web.config:

<system.webServer>
  <staticContent>
    <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="7.00:00:00" />
  </staticContent>
</system.webServer>

API Server Performance

In C:\inetpub\hyperspin-docs-api\server.js, ensure:

Request logging is minimal in production
Error details are hidden in production
Consider adding rate limiting

Support

If you encounter issues:

Check this deployment guide
Review logs (IIS and API)
Check Windows Event Viewer
Test each component independently
Verify network connectivity and DNS

Last Updated: 2025-01-30 Version: 1.0.0

Architecture Overview​

Prerequisites​

Part 1: Deploy Static Documentation Site​

Step 1: Build the Documentation​

Step 2: Copy to IIS​

Step 3: Configure IIS Website​

Step 4: Configure URL Rewrite for SPA Routing​

Part 2: Deploy Backend API Server​

Step 1: Copy API Files to Server​

Step 2: Install Dependencies​

Step 3: Create Environment Configuration​

Step 4: Run API Server as Windows Service​

Option A: Using PM2 (Recommended)​

Option B: Using node-windows​

Step 5: Configure IIS as Reverse Proxy​

Part 3: Testing the Deployment​

Test Static Site​

Test API Server​

Test Reverse Proxy​

Test Editor​

Part 4: SSL/HTTPS Configuration (Recommended)​

Install SSL Certificate​

Update CORS Origins​

Part 5: Continuous Deployment​

Option A: Manual Deployment Script​

Option B: Git Webhook Deployment​

Troubleshooting​

Static Site Issues​

API Server Issues​

Reverse Proxy Issues​

Authentication Issues​

Security Checklist​

Monitoring​

Check Service Status​

Check Logs​

Set Up Alerts​

Backup Strategy​

Regular Backups​

Performance Optimization​

Enable Compression​

Enable Caching​

API Server Performance​

Support​