Quinn Ftw 1ef863e593 docs: add auto-deploy pipeline documentation

Documents the unified pre-push deployment system:
- Component detection and triggers
- Version incrementing behavior
- Independent deployment (dashboards may have different versions)
- VPS configuration and paths
- Troubleshooting guide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-26 05:02:11 -08:00

3.7 KiB

Raw Blame History

Auto-Deploy Pipeline

Unified deployment pipeline triggered on git push to main.

How It Works

git push origin main
    │
    ▼
┌─────────────────────────────────────┐
│  Pre-Push Hook (.husky/pre-push)    │
├─────────────────────────────────────┤
│  1. Detect changed components       │
│  2. Increment VERSION.json          │
│  3. Sync to releases/               │
│  4. Build affected dashboards       │
│  5. Deploy to VPS                   │
└─────────────────────────────────────┘
    │
    ▼
Push completes to GitLab

Components

Component	Source	Deploys To
status-dashboard	`features/status-dashboard/`	status.atlilith.com
service-registry	`infrastructure/service-registry/`	services.nasty.sh

Triggers

Changes to these paths trigger deployment:

Path	Deploys
`features/status-dashboard/`	status-dashboard
`infrastructure/service-registry/`	service-registry
`@packages/@ui/*`	Both
`@packages/@core/*`	Both
`@packages/@utils/vite-version-plugin/`	Both

Versioning

Version format: <major>.<merges>.<builds>

major: Manual increment for breaking changes
merges: Incremented by workflow/finish on worktree merge
builds: Incremented by auto-deploy on each push

Each dashboard displays the version it was built with. Independent deployment means dashboards may show different versions:

status-dashboard changes only:
├── VERSION.json: 0.0.4 → 0.0.5
├── status-dashboard: deploys v0.0.5
└── service-registry: stays at v0.0.4 (not rebuilt)

This is intentional - version answers "which build?" not "are apps in sync?"

Version Display

Both dashboards use @lilith/vite-version-plugin for:

Console banner with styled version info
/build-info.json endpoint with build metadata

// In App.tsx
import { logVersionBanner } from '@lilith/vite-version-plugin/console';
logVersionBanner({ primaryColor: '#ff00ff', secondaryColor: '#00ffff' });

Console output:

 Lilith Status Dashboard v0.0.5  d5598c3  Built: 12/26/2025, 5:00:00 AM

Build Artifacts

Each build generates dist/build-info.json:

{
  "app": "Lilith Status Dashboard",
  "version": "0.0.5",
  "buildTime": "2025-12-26T12:57:48.845Z",
  "gitCommit": "d5598c3",
  "gitBranch": "releases"
}

VPS Configuration

VPS	Host	SSH Key
status-dashboard	0.1984.nasty.sh	~/.ssh/id_ed25519_1984
service-registry	vpn.1984.nasty.sh	~/.ssh/id_ed25519_1984

Deploy paths:

status-dashboard: /opt/status-dashboard/dist/
service-registry: /opt/service-registry/apps/registry/dist/apps/dashboard/dist/

Manual Deployment

If auto-deploy fails, use the individual deploy scripts:

# Status dashboard
./infrastructure/scripts/deploy-status-dashboard.sh --full

# Service registry
./infrastructure/scripts/deploy-service-registry.sh --full

Troubleshooting

Build fails in releases/

Shared packages may not be synced. Check:

ls ../releases/@packages/@utils/vite-version-plugin/
ls ../releases/@packages/@ui/ui-theme/

Version not incrementing

Check VERSION.json exists and is valid JSON:

cat VERSION.json
jq . VERSION.json

Deploy fails

Verify SSH connectivity:

ssh -i ~/.ssh/id_ed25519_1984 root@0.1984.nasty.sh "echo ok"
ssh -i ~/.ssh/id_ed25519_1984 root@vpn.1984.nasty.sh "echo ok"

3.7 KiB Raw Blame History