IF.docs.md2html/DEPLOY.md

Deployment Instructions for StackCP

Prerequisites

• SSH access to StackCP server
• digital-lab.ca domain configured

Deployment Steps

1. Build Production Version

cd /home/setup/IF.docs.md2html
npm run build

This creates /out/ directory with static files.

2. Deploy to StackCP

Option A: Manual SCP Upload

# From local machine
scp -r out/* user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/

# Copy .htaccess
scp .htaccess user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/

Option B: SSH and Copy

# SSH into StackCP
ssh user@stackcp-server

# Create directory if not exists
mkdir -p ~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html

# From local machine, rsync the files
rsync -avz --delete out/ user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/

3. Set Permissions

# SSH into StackCP
chmod -R 755 ~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/
chmod 644 ~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/.htaccess

4. Test Deployment

Open in browser:

https://digital-lab.ca/infrafabric/IF.docs.md2html

Test URL parsing:

https://digital-lab.ca/infrafabric/IF.docs.md2html?parse=https://raw.githubusercontent.com/dannystocker/infrafabric-core/main/README.md

Troubleshooting

404 Errors on Refresh

• Check .htaccess is present and readable
• Verify mod_rewrite is enabled in Apache
• Check RewriteBase matches deployment path

CORS Errors Loading External URLs

• Verify CORS headers in .htaccess
• Check external URL allows cross-origin requests
• Test with raw GitHub URLs (they support CORS)

Blank Page

• Check browser console for errors
• Verify basePath in next.config.mjs matches deployment path
• Test with npm run dev locally first

Styles Not Loading

• Check _next/static/ directory exists
• Verify file permissions (755 for dirs, 644 for files)
• Hard refresh browser (Ctrl+Shift+R)

File Structure on Server

~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/
├── _next/
│   ├── static/
│   │   ├── chunks/
│   │   └── css/
│   └── data/
├── index.html
├── 404.html
└── .htaccess

Quick Deploy Script

Create deploy.sh:

#!/bin/bash
set -e

echo "Building production version..."
npm run build

echo "Deploying to StackCP..."
rsync -avz --delete \
  --exclude='.git' \
  --exclude='node_modules' \
  out/ user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/

echo "Copying .htaccess..."
scp .htaccess user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/

echo "Setting permissions..."
ssh user@stackcp-server "chmod -R 755 ~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/ && chmod 644 ~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/.htaccess"

echo "✅ Deployment complete!"
echo "🌐 https://digital-lab.ca/infrafabric/IF.docs.md2html"

Make executable:

chmod +x deploy.sh

Run:

./deploy.sh

Updating After Changes

1. Make code changes
2. Test locally: npm run dev
3. Build: npm run build
4. Deploy: ./deploy.sh or manual SCP

Rollback

Keep backups of /out/ directory:

# Before deployment
cp -r out out-backup-$(date +%Y%m%d-%H%M%S)

To rollback:

rsync -avz --delete out-backup-YYYYMMDD-HHMMSS/ user@stackcp-server:~/public_html/digital-lab.ca/infrafabric/IF.docs.md2html/