Deployment Guide

WebMCP Auto-UI deployment relies on a centralized script (scripts/deploy.sh) that manages all seven monorepo apps with their specific paths and configurations. This guide covers the complete procedure, from local build to production verification.

Golden Rule

Never deploy manually

ALWAYS use ./scripts/deploy.sh. Never scp, rsync, or any other manual method.

Why? Each app has a different deployment path on the server, and repeated errors have been caused by deploying to the wrong location:

• rsync --delete wiped production .env files
• scp to the wrong folder served stale code for hours
• Orphaned JS chunks from previous builds polluted the browser cache

Target Infrastructure

graph LR
    DEV[Local machine<br/>build + deploy.sh] -->|SSH + SCP| SERVER[demo.hyperskills.net]

    subgraph SERVER["Production server"]
        NGINX[nginx<br/>:80/:443] -->|proxy| FLEX[flex :3007]
        NGINX -->|proxy| VIEWER[viewer :3008]
        NGINX -->|proxy| RECIPES[recipes :3009]
        NGINX -->|proxy| SHOWCASE[showcase :3010]
        NGINX -->|proxy| BOILER[boilerplate :3011]
        NGINX -->|static| HOME[home/]
        NGINX -->|static| TODO[todo/]
    end

Element	Value
Server	demo.hyperskills.net (via SSH alias ssh bot)
Base path	/opt/webmcp-demos/
Node.js apps	flex (:3007), viewer, recipes, showcase, boilerplate
Static apps	home, todo (served by nginx)
Reverse proxy	nginx on ports 80/443

Applications and Deployment Paths

Each app has a specific deployment path. The deploy.sh script knows these paths and handles them automatically.

App	Type	Build dir (local)	Deploy dest (server)	ExecStart	Notes
flex	Node.js (SvelteKit)	apps/flex/build/	/opt/webmcp-demos/flex/	node index.js	Main composer
viewer	Node.js (SvelteKit)	apps/viewer/build/	/opt/webmcp-demos/viewer/	node index.js	HyperSkills viewer
showcase	Node.js (SvelteKit)	apps/showcase/build/	/opt/webmcp-demos/showcase/	node index.js	Widget gallery
recipes	Node.js (SvelteKit)	apps/recipes/build/	/opt/webmcp-demos/recipes/	node index.js	Recipe explorer
boilerplate	Node.js (SvelteKit)	apps/boilerplate/build/	/opt/webmcp-demos/boilerplate/	node index.js	Starter template
home	Static (SvelteKit)	apps/home/build/	/opt/webmcp-demos/home/	N/A (nginx)	Homepage
todo	Static (SvelteKit)	apps/todo/build/	/opt/webmcp-demos/todo/	N/A (nginx)	Todo demo

Different paths

Node.js apps are deployed to the root of their folder (/opt/webmcp-demos/flex/index.js), because systemd runs node index.js from that directory. If you deploy to the wrong location, the service starts but serves stale code.

Deployment Procedure

Step 1: Deploy via the Script

The script handles everything: package builds, app builds, cleanup, transfer, integrity verification, and service restart.

# Deploy all apps
./scripts/deploy.sh

# Deploy a specific app
./scripts/deploy.sh flex

# Deploy multiple apps
./scripts/deploy.sh flex viewer home

# Preview what would be deployed without making changes
./scripts/deploy.sh --dry-run

# Deploy with documentation update
./scripts/deploy.sh --with-docs

Step 2: Verify on Server

ssh bot

# Check Node.js services
systemctl status webmcp-flex
systemctl status webmcp-viewer

# Check static apps
curl -s -o /dev/null -w "%{http_code}" http://localhost/home/

# Check nginx
sudo systemctl status nginx

What the Script Does

The deploy.sh script executes these steps in order:

flowchart TD
    A[Sync versions<br/>across all workspaces] --> B[Build packages<br/>core → sdk → ui → agent]
    B --> C{Apps to deploy?}
    C -->|Each app| D[Back up app<br/>on server]
    D --> E[Build app<br/>npm run build]
    E --> F[Clean old files<br/>on server]
    F --> G[Copy build<br/>via SCP]
    G --> H{SHA-256<br/>check?}
    H -->|Mismatch| I[Automatic rollback<br/>from backup]
    H -->|OK| J[Restart service<br/>systemd]
    J --> K[Final verification<br/>systemctl is-active]

Integrity Verification (SHA-256)

After each transfer, the script compares the SHA-256 hash of the local file with the deployed file:

expected=$(sha256sum apps/flex/build/index.js | cut -d' ' -f1)
actual=$(ssh bot "sha256sum /opt/webmcp-demos/flex/index.js | cut -d' ' -f1")

if [ "$expected" != "$actual" ]; then
  echo "INTEGRITY ERROR — sha256 mismatch, rolling back"
  rollback_app "flex"
fi

This check catches incomplete transfers, read-only files, and stale builds.

Backup and Rollback

Before each deployment, a full copy of the existing app is stored in /opt/webmcp-demos/.backups/. On failure, the script automatically restores the previous version.

# Manual rollback if needed
ssh bot
cp -a /opt/webmcp-demos/.backups/flex.prev /opt/webmcp-demos/flex
systemctl restart webmcp-flex

Environment Variables

On the Server (Production)

.env files must exist before the first deployment. They are created manually once and never deployed by the script.

Never deploy .env files

.env files contain API keys and secrets. They must never be in git or copied by the deployment script. If an .env disappears from the server (rsync incident of 2026-04-06), recreate it manually.

Build-Time Variables (home)

The home app requires PUBLIC_BASE_URL at build time, not runtime:

# deploy.sh handles this automatically for static apps (home, todo)
PUBLIC_BASE_URL=https://demos.hyperskills.net npm run build

If you build manually (outside the script), remember this variable, otherwise internal links will point to localhost.

nginx Configuration

nginx serves as reverse proxy for Node.js apps and static file server for the rest:

# Node.js apps → proxy to local port
location /flex/ {
  proxy_pass http://localhost:3007/;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection 'upgrade';
}

# Static apps → serve from disk
location /home/ {
  alias /opt/webmcp-demos/home/;
  try_files $uri $uri/index.html =404;
}

# Default page = home
location / {
  alias /opt/webmcp-demos/home/;
  try_files $uri $uri/index.html =404;
}

Production Monitoring

Logs

ssh bot

# Follow logs in real time
journalctl -u webmcp-flex -f

# View the last 50 log entries
journalctl -u webmcp-flex -n 50 --no-pager

Health Checks

# Test all apps
for app in home flex viewer showcase recipes; do
  code=$(curl -s -o /dev/null -w "%{http_code}" "https://demos.hyperskills.net/$app/")
  echo "$app: HTTP $code"
done

System Resources

ssh bot
df -h       # Disk space
free -h     # Memory

Troubleshooting

App Shows Stale Code After Deploy

Likely cause: orphaned JavaScript chunks. If you deployed manually (without the script), old .js files remain and the browser serves them from cache.

Solution:

ssh bot
# Clean old files
rm -rf /opt/webmcp-demos/flex/client /opt/webmcp-demos/flex/server
# Redeploy properly
./scripts/deploy.sh flex

The script cleans automatically

deploy.sh performs targeted cleanup before each copy (removes index.js, handler.js, client/, server/, build/). This cleanup is the main reason to use the script over manual scp.

.env Missing After Deploy

Cause: .env files are not part of the deploy and must never be.

Solution: recreate the file manually on the server, then restart the service.

nginx Returns 404

Diagnosis:

ssh bot

# Verify files exist
ls -la /opt/webmcp-demos/home/index.html

# Test nginx config
sudo nginx -t

# Check paths in config
grep -A 5 "location /home/" /etc/nginx/sites-available/default

# Reload after fix
sudo systemctl reload nginx

API Rate-Limited (LLM Provider)

Symptom: 429 errors in flex logs.

Solutions:

1. Wait (the client handles exponential backoff automatically)
2. Reduce maxIterations in agent configuration
3. Verify the API key is not shared across multiple deployments

Service Does Not Start

ssh bot

# View detailed error
journalctl -u webmcp-flex -n 30 --no-pager

# Common causes:
# - Port already in use → lsof -i :3007
# - Missing .env → ls -la /opt/webmcp-demos/flex/.env
# - Missing npm deps → cd /opt/webmcp-demos/flex && npm install --production

Routine Maintenance

Restart All Services

ssh bot
sudo systemctl restart webmcp-flex webmcp-viewer webmcp-recipes webmcp-showcase nginx

Clean Old Logs

ssh bot
journalctl --vacuum-time=7d  # Keep 7 days

Update Dependencies

# Locally
npm update
npm run build
./scripts/deploy.sh

Deployment Checklist

Before each deployment, verify:

• Local build succeeds (npm run build without errors)
• Tests pass (npm run test)
• Code is committed and pushed
• Using ./scripts/deploy.sh (never scp or rsync)
• After deploy: check logs (journalctl -u webmcp-flex -n 20)
• After deploy: test in browser
• If deploying home: verify PUBLIC_BASE_URL is correct

Emergency Rollback

If a deployment breaks something and the automatic rollback did not work:

# Option 1: Restore from backup
ssh bot
cp -a /opt/webmcp-demos/.backups/flex.prev /opt/webmcp-demos/flex
systemctl restart webmcp-flex

# Option 2: Redeploy an earlier version
git checkout <previous_commit>
./scripts/deploy.sh flex

Rollback speed

The backup only contains the immediately previous version (*.prev). If you deploy twice in a row, the first backup is overwritten. When in doubt, check the backup contents before restoring.