# TR-069 (GenieACS) → TR-369 (Oktopus) Migration Plan

## Why Migrate

1. **GenieACS maintenance risk** — single maintainer, slow release cadence, Node.js/MongoDB stack aging
2. **TR-069 is polling-based** — CPE connects every X minutes, no real-time push. Reboot command waits for next inform.
3. **TR-369 (USP) is the ITU/BBF successor** — MQTT/WebSocket transport, bidirectional, real-time, certificate-based auth
4. **Oktopus is actively developed** — Go-based, NATS messaging, supports both TR-069 and TR-369

## Current GenieACS Architecture

```
CPE fleet (TR-069)
    │ HTTP/SOAP (CWMP)
    ▼
96.125.192.25 — GenieACS Core (CWMP, NBI, FS)
    │
    ▼
10.5.2.125 — MongoDB (devices, tasks, faults, provisions)
    │
    ▼
10.5.2.124 — GenieACS GUI (admin portal)
    │
    ▼
targo-hub /devices/* — Ops UI integration
```

## Target Oktopus Architecture

```
CPE fleet (TR-369 USP + legacy TR-069)
    │
    ├── MQTT/WebSocket (USP) ──▶ Oktopus Controller
    │                               │
    ├── HTTP/SOAP (CWMP) ──────▶ Oktopus TR-069 Adapter
    │                               │
    │                               ▼
    │                           NATS (internal messaging)
    │                               │
    │                               ▼
    │                           PostgreSQL / TimescaleDB
    │
    ▼
targo-hub /devices/* — Ops UI integration (same endpoints, new backend)
```

## Migration Phases

### Phase 0: Export & Document (NOW)
- Run `scripts/migration/export_genieacs.sh` on GenieACS server
- Catalog all provisions, presets, virtual parameters
- Document each provision's purpose and parameter paths
- Download all firmware files from GridFS

### Phase 1: Deploy Oktopus with TR-069 Adapter (Parallel Run)
- Deploy Oktopus CE alongside GenieACS (different port/IP)
- Enable Oktopus TR-069 adapter to accept CWMP connections
- Point a small test group of CPEs (5-10 units) to Oktopus
- Verify: inform, reboot, parameter read/write, firmware upgrade
- Keep GenieACS running for the rest of the fleet

### Phase 2: Reproduce Provisions in Oktopus
- Map each GenieACS provision to Oktopus equivalent:

| GenieACS Concept | Oktopus Equivalent |
|---|---|
| Provision script (JS) | USP Set/Get/Operate messages + webhooks |
| `declare(path, ...)` | USP Get/Set on TR-181 path (same paths!) |
| `ext('script', ...)` | Oktopus webhook to targo-hub |
| Preset (trigger rule) | Device group + event subscription |
| Preset tag filter | Oktopus device group membership |
| Preset event (inform/boot) | MQTT topic subscription |
| Virtual parameter | Oktopus computed metric or targo-hub enrichment |
| File (firmware) | Oktopus firmware repository |

### Phase 3: Gradual CPE Migration
- Update CPE ACS URL via GenieACS setParameterValues:
  ```
  Device.ManagementServer.URL = "https://acs-new.gigafibre.ca"
  ```
- Migrate in batches: 50 → 500 → all
- Monitor for faults, missed informs, failed tasks
- Keep GenieACS read-only as fallback for 30 days

### Phase 4: TR-369 Firmware Upgrade
- For CPEs that support USP (newer models):
  - Push firmware with TR-369 agent enabled
  - Configure USP controller URL and MQTT broker
  - Migrate from TR-069 adapter to native TR-369
- For legacy CPEs (TR-069 only):
  - Keep on Oktopus TR-069 adapter permanently
  - Replace hardware on failure with TR-369 capable units

### Phase 5: Decommission GenieACS
- Verify 100% of fleet reports to Oktopus
- Archive MongoDB data (export to JSON/PostgreSQL)
- Shut down GenieACS servers
- Update targo-hub to point to Oktopus API instead of GenieACS NBI

## targo-hub Integration Changes

The `/devices/*` endpoints in targo-hub currently proxy GenieACS NBI. For Oktopus:

```
# Current (GenieACS NBI)
GENIEACS_NBI_URL=http://10.5.2.115:7557

# Future (Oktopus API)
OKTOPUS_API_URL=https://oss.gigafibre.ca/api
```

The `summarizeDevice()` function already handles both TR-098 and TR-181 parameter paths, so the Ops UI won't need changes — only the backend proxy target.

## CPE Compatibility Check

Before migration, verify each CPE model's protocol support:

| Model | TR-069 | TR-369 | Notes |
|---|---|---|---|
| ZTE F670L | ✅ | ❌ | Legacy, keep on TR-069 adapter |
| ZTE F680 | ✅ | ✅ | Firmware update enables USP |
| Huawei HG8245H | ✅ | ❌ | Legacy |
| Nokia G-010G-Q | ✅ | ✅ | USP via firmware 3.x+ |

(Fill in with actual fleet models after running device summary export)

## Risk Mitigation

1. **GenieACS stays running** during entire migration — no big bang cutover
2. **Same TR-181 data model** — parameter paths don't change
3. **targo-hub abstraction layer** — Ops UI doesn't care which ACS backend serves `/devices/*`
4. **Export script** preserves all business logic — can recreate GenieACS from scratch if needed
5. **Oktopus TR-069 adapter** means even legacy CPEs work without firmware changes

## Timeline Estimate

| Phase | Duration | Prerequisite |
|---|---|---|
| Phase 0: Export | 1 day | SSH access to GenieACS |
| Phase 1: Parallel deploy | 1 week | Oktopus server provisioned |
| Phase 2: Reproduce provisions | 1-2 weeks | Understanding of all scripts |
| Phase 3: CPE migration | 2-4 weeks | Phase 2 validated |
| Phase 4: TR-369 firmware | Ongoing | CPE vendor firmware availability |
| Phase 5: Decommission | 1 day | 30 days after Phase 3 |