Upgrading and rollback

Upgrade

1. Read first. The new archive's docs/known-limits.md, the migration notes for migrations you have not applied yet, and the new settings in docs/runbooks/configuration.md.
2. Stop the phone in a maintenance window: stop eureka_phone. FXServer stops eureka_duo and every other phone page with it.
3. Back up. Dump the database with the migrator account and prove the dump restores into a scratch database. Back up the object store with your provider's tools (bucket versioning or a copy). Keep a copy of your current resources/eureka_phone and resources/eureka_duo folders, including the config files you edited.
4. Apply the new migrations with the new archive's tool, exactly as in Installation: status, up, status.
5. Replace the folders with the new archive's eureka_phone and eureka_duo. Then carry your changes over by comparing each of your edited files with the new one: eureka_phone/config/offers.lua, valet.lua, services.lua, emergency.lua, jobs.lua and client.lua, and eureka_duo/config/client.lua. A release can add entries, so never copy an old file over a new one unread.
6. Start again: refresh, ensure eureka_phone, then ensure eureka_duo. Check for [eureka_phone] info READY and run the short list of the release smoke test.

Roll back

• Code only, when the new release added no migration: stop the phone, put back the previous eureka_phone and eureka_duo folders, start them. An older build also starts on a newer schema (it logs SCHEMA_AHEAD), but rely on that only when the release notes say the migrations are compatible with the old build.
• With a migration: stop the phone, restore the database backup (and the object store if the release changed media), put back the previous folders, start. Everything players did since the backup is lost.
• A migration stopped partway: the phone refuses to start on a partial schema (SCHEMA_PARTIAL), whichever build runs. The archive's docs/runbooks/database-migrations.md ("When up does not finish") walks through resuming it.