Upgrading

GridWork HQ uses semantic versioning. This page covers the upgrade process and version-specific migration steps.

General Upgrade Process

Local Setup

cd ~/agency-workspace/gridwork-hq
git pull origin main
npm install
bun run migrate  # Apply database schema changes
npm run build

cd ~/agency-workspace/pipeline-server
git pull origin main
npm install
# Restart the pipeline server

VPS

# Dashboard
cd /var/www/gridwork-hq
git pull origin main
npm install
bun run migrate
npm run build
pm2 restart gridwork-hq

# Pipeline server
cd /var/www/pipeline-server
git pull origin main
npm install
sudo systemctl restart agency-pipeline

Vercel

Push to your main branch. Vercel auto-deploys. Then update the pipeline server on your local machine:

cd ~/agency-workspace/pipeline-server
git pull origin main
npm install
# Restart the pipeline server

What Is Preserved

Your configuration files are gitignored and will not be overwritten by pulls:

• gridwork-hq/.env.local
• gridwork-hq/config/brand.json
• pipeline-server/.env
• pipeline-server/cron-config.json

Version-Specific Migration

v1.1 to v1.2

After pulling v1.2 updates:

1. Run bun run migrate in gridwork-hq/ to apply SQLite schema changes (Drizzle ORM replaces Vercel KV)
2. The CSS token system (gw-* custom properties) now supports dark/light mode
3. Docker support added — Dockerfile and docker-compose.yml are new files
4. WelcomeBanner onboarding flow is new — appears on first login
5. SSE rate limiting is now active on the pipeline server (20 connections/min per IP)
6. Cron command allowlist is now enforced — verify your shell cron commands are in the allowlist

v1.0 to v1.1

1. Bearer token moved from query string to Authorization header — update any direct API calls
2. All pipeline traffic now routes through HQ API proxy
3. Zep Cloud integration removed — see ADVANCED_EXTENSIONS.md to re-add if needed
4. NEXT_PUBLIC_PIPELINE_URL removed — use PIPELINE_SERVER_URL instead

Checking Your Version

Both package.json files contain the version number. They should match.

cd ~/agency-workspace/gridwork-hq && node -e "console.log(require('./package.json').version)"
cd ~/agency-workspace/pipeline-server && node -e "console.log(require('./package.json').version)"