Pulse/docs/installer-v2-rollout.md

# Installer v2 Rollout Plan

## 1. Overview

The Docker agent installer (`install-docker-agent.sh`) has been refactored into a
modular, testable v2. Key improvements include:

- Shared library usage (`scripts/lib/*.sh`) for logging, HTTP, and systemd
  helpers, reducing duplication and easing maintenance.
- Support for `--dry-run`, enabling administrators to preview actions safely.
- Bundled single-file distribution generated by `scripts/bundle.sh` for curl
  based installs, while keeping modular sources in the repository.
- New smoke and integration tests to catch regressions.

Benefits:

- **Users:** Clearer logging, dry-run validation, safer rollbacks, and improved
  error handling.
- **Developers:** Consistent helper functions, faster iteration on fixes, and
  reusable testing infrastructure.

## 2. Rollout Strategy

### Phase 1: Alpha Testing (Internal)
- Enable v2 via feature flag for internal environments only.
- Exercise on development clusters, CI agents, and dogfood installations.
- Validate dry-run, full install, multi-target, and uninstall scenarios.
- Duration: ~1 week.

### Phase 2: Beta Testing (Early Adopters)
- Announce availability in release notes and internal channels.
- Provide explicit opt-in instructions (`PULSE_INSTALLER_V2=1`).
- Monitor install success metrics, support channels, and gather structured
  feedback from operators.
- Duration: ~2 weeks.

### Phase 3: General Availability
- Flip feature flag default to v2 while retaining v1 as fallback for one full
  release cycle.
- Publish deprecation notice for the legacy installer.
- After the grace period, remove v1 from distribution.
- Duration: 1 release cadence (approx. 4–6 weeks).

## 3. Feature Flag Mechanism

Users can select installer versions via environment variable:

```bash
# Enable v2 (early adopter)
export PULSE_INSTALLER_V2=1
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- ...

# Force legacy v1
export PULSE_INSTALLER_V2=0
curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- ...

# Server-side pseudo-code
if [[ "${PULSE_INSTALLER_V2:-0}" == "1" ]]; then
  serve dist/install-docker-agent.sh
else
  serve scripts/install-docker-agent-legacy.sh
fi
```

The download endpoint should inspect the flag (query parameter, header, or
environment variable) and serve the appropriate script.

## 4. Testing Checklist

### Before Rollout
- [ ] Smoke tests (`scripts/tests/run.sh`) passing
- [ ] Integration tests (`scripts/tests/integration/...`) passing
- [ ] Ubuntu 20.04 & 22.04 validated
- [ ] Debian 11 & 12 validated
- [ ] With and without Docker binary
- [ ] Multi-target configuration verified
- [ ] Uninstall path verified
- [ ] Documentation updated (INSTALL, FAQ, etc.)
- [ ] Release notes drafted

### During Rollout
- [ ] Monitor error rates (CI dashboards, telemetry)
- [ ] Watch support channels/tickets for installer issues
- [ ] Sample successful installations daily
- [ ] Collect structured feedback from early adopters

## 5. Success Metrics

- Installation success rate ≥ 99%
- Median installation duration (baseline ±10%)
- Top error categories and frequency trending downward
- Positive/neutral user feedback (no significant negative trend)
- Rollback requests < 1%

## 6. Rollback Plan

If blocking issues surface:

### Quick Rollback (< 5 minutes)
1. Replace served script with v1 variant:
   ```bash
   cp scripts/install-docker-agent-legacy.sh /var/www/html/install-docker-agent.sh
   # or update symlink pointing to dist/install-docker-agent.sh
   ```
2. Update documentation to reflect temporary rollback.
3. Broadcast notice in release channels/support chat.

**File references**
- Legacy: `scripts/install-docker-agent-legacy.sh`
- Bundled v2: `dist/install-docker-agent.sh`
- Served location: `/download/install-docker-agent.sh` (symlink/HTTP root)

## 7. Communication Plan

**Announcements**
- Release notes covering v2 highlights and rollout phases.
- Update product docs (`INSTALL.md`, quick reference).
- Post in GitHub Discussions / community forums.
- Optional blog post for broader awareness.

**User Guidance**
- Explain how to opt-in/out using `PULSE_INSTALLER_V2`.
- Highlight new capabilities (`--dry-run`, improved messaging).
- Provide support contact and bug-reporting instructions.
- Link to troubleshooting resources.

## 8. Known Limitations

- Limited testing on non-`systemd` init systems (manual startup handled but not
  optimized).
- ARM architectures covered via dry-run and download stubs; on-device testing
  pending.
- Requires Bash 4.0+ (same as v1) — document for older environments.

## 9. Post-Rollout Tasks

- [ ] Remove feature flag after one successful release cycle.
- [ ] Retire legacy installer artifacts and adjust CI pipelines.
- [ ] Update all docs to reference v2 only.
- [ ] Apply modular pattern to remaining installers (install.sh,
      install-sensor-proxy.sh, pulse-auto-update.sh).
- [ ] Expand integration tests to cover additional distributions and scenarios.