# Migration and rollback

This procedure keeps the hosted dashboard and both Shields working until the local service has passed its checks.

## 1. Prepare the server

1. Extract the release bundle on the internal container host.
2. Regenerate the private Google Calendar ICS URLs that were used during development.
3. Run `scripts/configure.sh` or `scripts/configure.ps1`.
4. Review `.env`, especially the bind address, port, timezone, and NWS grid.
5. Start the container with `docker compose up -d --build --wait`.

Do not expose port 8080 to the public Internet.

## 2. Validate before touching a Shield

Check liveness:

```bash
curl -fsS http://SERVER-IP:8080/api/health
```

In trusted-LAN mode, open `http://SERVER-IP:8080/` and verify:

- calendar events appear in agenda, week, and month views;
- the seven-day forecast and sunrise/sunset values appear;
- the FRED ticker reports live or partial data;
- AI/tech headlines appear and their QR dialogs scan correctly.

In bearer mode, validate with a client capable of adding the `Authorization` header or proceed with one Shield as the test client.

## 3. Upgrade one Shield first

Use the Shield with the least operational impact as the canary:

```powershell
& $adb -s DEVICE:5555 install -r .\shield\Hobbs-Family-Organizer-Local-v1.4.apk
```

The `-r` upgrade is important. It preserves app-private files, including the legacy hosted token and the `daily_wake_0630_enabled` schedule flag.

Configure the local server:

```powershell
.\shield\configure-shield.ps1 `
  -Device DEVICE:5555 `
  -BaseUrl http://SERVER-IP:8080/ `
  -AllowInsecureHttp `
  -AdbPath $adb
```

Add `-TokenFile .\secrets\organizer_access_token.txt` if bearer mode is enabled. Omit `-AllowInsecureHttp` for HTTPS.

Verify remote navigation, automatic refresh, QR dialogs, reboot behavior, and the 6:30 AM alarm on any Shield where that schedule was already enabled.

## 4. Upgrade the second Shield

After the canary has run successfully, repeat the APK upgrade and configuration with the other device address.

## 5. Rollback

The local cutover does not delete the old hosted access token. To switch a Shield back:

```powershell
.\shield\restore-hosted-site.ps1 -Device DEVICE:5555 -AdbPath $adb
```

This removes `base_url`, `access_token`, and `allow_insecure_http`, then relaunches the same app against the hosted Site.

To roll back the server release, restore the previous release directory and its protected configuration backup, then run `docker compose up -d --build --wait`.

## 6. After the observation period

Once the local deployment is stable:

- keep the hosted Site only as long as you want the rollback option;
- retain an encrypted configuration backup;
- keep the prebuilt signed APK with the release archive;
- document the server address/DNS record and certificate renewal process;
- periodically review outbound-feed failures in `docker compose logs organizer`.