harb/QUICKSTART_MIGRATION.md

Quick Start: CI Migration Testing

Status: ✅ Ready to Build & Test

All code is written. Follow these steps to activate the new CI infrastructure.

---

Step 1: Build the Integration Image (~5-10 min)

cd /home/debian/harb-ci
./scripts/build-integration-image.sh

What it does: Builds a Docker image containing the full Harb stack Expected output: ✓ Image built successfully: registry.sovraigns.network/harb/integration:latest

---

Step 2: Test Locally (Optional, ~5 min)

# Terminal 1: Start the stack
docker run --rm --privileged -p 8081:8081 \
  registry.sovraigns.network/harb/integration:latest

# Terminal 2: Wait for healthy (~60-90s)
timeout 300 sh -c 'until curl -sf http://localhost:8081/api/graphql; do sleep 5; done'
echo "Stack is healthy!"

# Terminal 3: Run E2E tests
cd /home/debian/harb-ci
npm run test:e2e

# Cleanup: Ctrl+C in Terminal 1

---

Step 3: Push to Registry

# Login to registry
docker login registry.sovraigns.network -u ciuser
# Password: (ask admin or check /etc/docker/registry/htpasswd)

# Push image
docker push registry.sovraigns.network/harb/integration:latest

---

Step 4: Activate New Pipeline

cd /home/debian/harb-ci

# Backup old E2E pipeline
mv .woodpecker/e2e.yml .woodpecker/e2e-old.yml

# Activate new pipeline
mv .woodpecker/e2e-new.yml .woodpecker/e2e.yml

# Stage all changes
git add -A

# Commit
git commit -m "ci: migrate to composite integration service

- Migrate agent from Podman to Docker
- Create composite harb/integration image
- Refactor E2E pipeline to use service pattern
- Eliminate Docker-in-Docker complexity
- Expected improvement: ~3-5 min faster E2E runs"

# Push to trigger CI
git push origin feature/ci

---

Step 5: Monitor CI Run

1. Open Woodpecker UI: https://ci.sovraigns.network
2. Navigate to johba/harb repository
3. Find the pipeline for your latest push
4. Watch the e2e pipeline:
   • Service: stack should start and become healthy (~60-90s)
   • Step 1: wait-for-stack should succeed
   • Step 2: run-e2e-tests should pass
   • Step 3: collect-artifacts should gather results

---

Troubleshooting

Build fails: "kraiken-lib build failed"

# Test kraiken-lib build separately
./scripts/build-kraiken-lib.sh

# Check for errors, fix, then rebuild
./scripts/build-integration-image.sh

Local test: Stack doesn't start

# Check Docker daemon is running
docker info

# Check disk space (need ~10GB)
df -h
docker system df

# View container logs
docker logs <container-id>

CI: Healthcheck timeout

• Cause: First run pulls images, takes longer (~2-3 min)
• Fix: Increase start_period in .woodpecker/e2e-new.yml line 18:

  start_period: 180s  # was 120s
  

CI: "Image not found"

• Cause: Forgot to push to registry
• Fix: Run Step 3 (push to registry)

---

Rollback (if needed)

# Restore old pipeline
mv .woodpecker/e2e-old.yml .woodpecker/e2e.yml

git add .woodpecker/e2e.yml
git commit -m "ci: rollback to DinD E2E pipeline"
git push

---

File Checklist

All files created and ready:

• docker/Dockerfile.integration - Integration image definition
• docker/integration-entrypoint.sh - Startup script
• docker-compose.ci.yml - CI compose file
• scripts/build-integration-image.sh - Build automation
• .woodpecker/e2e-new.yml - New E2E pipeline
• CI_MIGRATION.md - Full documentation
• MIGRATION_SUMMARY.md - Change summary
• QUICKSTART_MIGRATION.md - This file

---

Expected Timeline

Step	Time	Can Skip?
1. Build image	5-10 min	No
2. Local test	5 min	Yes (recommended though)
3. Push to registry	1 min	No
4. Activate pipeline	1 min	No
5. Monitor CI	5-6 min	No
Total	17-23 min	-

---

Success Indicators

✅ Build succeeds: Image tagged as registry.sovraigns.network/harb/integration:latest ✅ Local test passes: GraphQL endpoint responds, Playwright tests pass ✅ Registry push succeeds: Image visible in registry ✅ CI pipeline passes: All steps green in Woodpecker UI ✅ Performance improved: E2E run completes in ~5-6 min (was 8-10 min)

---

Next Actions

After successful CI run:

1. Monitor stability - Run a few more PRs to ensure consistency
2. Update documentation - Add new CI architecture to CLAUDE.md
3. Clean up - Remove .woodpecker/e2e-old.yml after 1 week
4. Optimize - Consider multi-stage builds for faster rebuilds
5. Consolidate - Merge CI images (Dockerfile.node-ci + Dockerfile.playwright-ci)

---

Questions? See CI_MIGRATION.md for detailed documentation.