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)

```bash
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)

```bash
# 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

```bash
# 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

```bash
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"
```bash
# 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
```bash
# 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:
  ```yaml
  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)

```bash
# 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:

- [x] `docker/Dockerfile.integration` - Integration image definition
- [x] `docker/integration-entrypoint.sh` - Startup script
- [x] `docker-compose.ci.yml` - CI compose file
- [x] `scripts/build-integration-image.sh` - Build automation
- [x] `.woodpecker/e2e-new.yml` - New E2E pipeline
- [x] `CI_MIGRATION.md` - Full documentation
- [x] `MIGRATION_SUMMARY.md` - Change summary
- [x] `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.