Skip to main content

GitHub Actions Deployment - Editor Integration

This document explains how the GitHub Actions workflows have been updated to support the built-in editor deployment.

What Changed​

1. web.config Now Includes API Reverse Proxy​

The generated web.config file now includes an API reverse proxy rule that routes /api/* requests to the Node.js backend:

<!-- API Reverse Proxy - Must be first! -->
<rule name="API Reverse Proxy" stopProcessing="true">
  <match url="^api/(.*)" />
  <action type="Rewrite" url="http://localhost:3001/api/{R:1}" />
</rule>

Important: This rule must be processed BEFORE the Docusaurus SPA routing rule.

2. Automated API Server Deployment​

Both workflows now include an optional "Deploy API Server" step that:

  • Copies api/ files to D:\hyperai_data\docs-api
  • Installs production dependencies
  • Restarts the PM2 service automatically

First-Time Setup (One-Time Only)​

Before the GitHub Actions can manage the API server, you need to set it up once:

Step 1: Manually Deploy API First Time​

On your self-hosted runner / IIS server:

# Create directory
mkdir D:\hyperai_data\docs-api
cd D:\hyperai_data\docs-api

# Copy files (first deployment)
# Copy from your repo or clone directly
git clone https://github.com/HyperSpin-LLC/HyperSpin-Docs.git temp
xcopy /E /I temp\api\* D:\hyperai_data\docs-api\
rmdir /S /Q temp

# Install dependencies
npm install --production

Step 2: Create .env File​

Create D:\hyperai_data\docs-api\.env:

GITHUB_TOKEN=ghp_your_github_token_here
GITHUB_OWNER=HyperSpin-LLC
GITHUB_REPO=HyperSpin-Docs
GITHUB_DEFAULT_BRANCH=main

API_PORT=3001
API_AUTH_TOKEN=your_secure_random_token_here

ALLOWED_ORIGINS=https://docs.hyperai.io

NODE_ENV=production

Important: This .env file will never be overwritten by deployments.

Step 3: Install PM2 and Create Service​

# 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 D:\hyperai_data\docs-api
pm2 start server.js --name hyperspin-docs-api
pm2 save

# Configure to start on boot
pm2 startup

Step 4: Enable IIS Proxy Features​

  1. Install URL Rewrite Module:

  2. Install Application Request Routing (ARR):

  3. 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

Ongoing Deployments (Automatic)​

After the first-time setup, every deployment will:

On Push to Main (deploy.yml)​

1. Checkout code
2. Install dependencies
3. Build Docusaurus site
4. Copy build/ to D:\hyperai_data\docs.hyperai.io\
5. Generate web.config with proxy rules
6. Copy api/ files to D:\hyperai_data\docs-api\
7. npm install in API directory
8. Restart PM2 service: pm2 restart hyperspin-docs-api

Manual Deployment (manual-deploy.yml)​

Same as above, but you can choose environment:

  • production → D:\hyperai_data\docs.hyperai.io
  • staging → D:\hyperai_data\docs-staging.hyperai.io
  • test → D:\hyperai_data\docs-test.hyperai.io

What Happens During Deployment​

Static Site​

✅ Build output copied to IIS folder ✅ web.config generated with proxy rules ✅ IIS serves static files

API Server​

✅ New code copied (preserves .env) ✅ Dependencies updated ✅ PM2 service restarted automatically ✅ Zero downtime (PM2 handles graceful reload)

Monitoring Deployments​

Check GitHub Actions​

  1. Go to your repository
  2. Click "Actions" tab
  3. View workflow runs
  4. Check logs for any errors

Check API Service on Server​

# Check service status
pm2 status

# View logs
pm2 logs hyperspin-docs-api

# Restart manually if needed
pm2 restart hyperspin-docs-api

Verify Deployment​

  1. Test static site: https://docs.hyperai.io
  2. Test API health: https://docs.hyperai.io/api/health
  3. Test editor:
    • Visit any doc page
    • Click "Edit this page"
    • Login with test credentials
    • Verify editor opens

Troubleshooting​

API Deployment Step Fails​

The deployment will continue even if API step fails (continue-on-error: true).

Check:

# On self-hosted runner, check logs
pm2 logs hyperspin-docs-api --lines 50

# Restart service
pm2 restart hyperspin-docs-api

PM2 Service Not Found​

If you see: "⚠️ PM2 service 'hyperspin-docs-api' not found"

Solution:

cd D:\hyperai_data\docs-api
pm2 start server.js --name hyperspin-docs-api
pm2 save

API Proxy Not Working​

Check IIS:

  1. Verify ARR is enabled (see setup steps above)
  2. Check web.config has proxy rules
  3. Test direct connection: curl http://localhost:3001/api/health

Environment Variables Not Set​

If API won't start, check .env file exists and has all required variables:

# View .env (without exposing secrets)
Test-Path D:\hyperai_data\docs-api\.env
# Should return True

# Verify service can start
cd D:\hyperai_data\docs-api
node server.js
# Should show: "Server running on port 3001"

Security Considerations​

Protected Files​

These files are NEVER overwritten by deployment:

  • .env - Your secrets and configuration
  • .env.example - Template file (safe to overwrite)

GitHub Token Permissions​

The GITHUB_TOKEN in .env needs:

  • repo scope for read/write access
  • Kept server-side only (never exposed to frontend)

API Authentication Token​

The API_AUTH_TOKEN should be:

  • Strong random string (generate with: openssl rand -hex 32)
  • Shared with frontend (they send this in accessToken param)
  • Rotated periodically

Advanced Configuration​

Multiple Environments​

If using staging/test environments, create separate API instances:

# Staging API
mkdir D:\hyperai_data\docs-api-staging
# Copy .env with staging-specific values
pm2 start server.js --name hyperspin-docs-api-staging -- --env staging

# Test API
mkdir D:\hyperai_data\docs-api-test
pm2 start server.js --name hyperspin-docs-api-test -- --env test

Then update workflows to deploy to correct API path based on environment.

Custom API Port​

If you need to run on a different port:

  1. Update .env: API_PORT=3002
  2. Update web.config proxy rule: http://localhost:3002/api/{R:1}
  3. Restart PM2: pm2 restart hyperspin-docs-api

Rollback Procedure​

If deployment fails or introduces issues:

Rollback Static Site​

# Restore previous build from Git
git checkout HEAD~1
npm run build
xcopy /S /Y .\build\* D:\hyperai_data\docs.hyperai.io\

Rollback API​

# Git restore
cd D:\hyperai_data\docs-api
git pull origin main
git checkout HEAD~1
npm install --production
pm2 restart hyperspin-docs-api

Or manually revert to previous commit in GitHub and trigger deployment.

Best Practices​

  1. Test in staging first - Use manual-deploy workflow with staging environment
  2. Monitor PM2 logs - Check for errors after deployment
  3. Keep .env backed up - Store securely offline
  4. Rotate tokens regularly - Update GitHub and API tokens periodically
  5. Use separate accounts - GitHub token should be from a bot/service account

Support​

If you encounter deployment issues:

  1. Check GitHub Actions workflow logs
  2. Check PM2 logs: pm2 logs hyperspin-docs-api
  3. Check Windows Event Viewer
  4. Verify IIS configuration
  5. Test each component independently

Last Updated: 2025-01-30 Version: 1.0.0