Add noble migration instructions

[legoktm]

Status

Ready for review

Description of Changes

• Description: Documentation for the noble migration.

Testing

Release

• should be published as part of 2.12.0 changes

Checklist (Optional)

• Doc linting (make docs-lint) passed locally
• Doc link linting (make docs-linkcheck) passed
• You have previewed (make docs) docs at http://localhost:8000

[legoktm]

Still WIP; needs some links and other stuff added. A few placeholders around dates need figuring out. Just wanted to post this so people can see the general direction.

[nathandyer]

Thanks @legoktm, this looks great! I think it covers all the questions I would have as an admin. The only thing missing that I'm seeing is a recommendation for folks to take a backup, just to be on the safe side. Is there any reason we wouldn't want to advise that beforehand?

[legoktm]

The only thing missing that I'm seeing is a recommendation for folks to take a backup, just to be on the safe side. Is there any reason we wouldn't want to advise that beforehand?

The upgrade script already takes a backup, except it leaves it on the app server. Transferring it to the Admin Workstation could be slow, especially if it's SSH-over-Tor. Of course, people who don't have local access probably benefit the most from having a backup on the AW.

It didn't really hit me until now, but in the manual case, we can just automatically start the backup for them as step 0. And then clean it up once we're done. The server will generate its own backup still, but that's not an issue.

[legoktm]

It didn't really hit me until now, but in the manual case, we can just automatically start the backup for them as step 0. And then clean it up once we're done. The server will generate its own backup still, but that's not an issue.

This ended up being more complicated technically than I anticipated, so for now I've just added a bullet to run the backup script first.

[legoktm]

Marking this as ready for review. Key highlights:

• terminology is "semi-automated upgrade" and "fully automated upgrade".
• I've tentatively set March 21, 2025 as the deadline to semi-automatically upgrade. Depending on the final release time, that gives folks 2-3 weeks. I think we can revisit this after the release and extend it if necessary.
• Mentioned that we'll publish technical details in the future - I think we should do it before the release, but this allows the docs PR to land first.

[nathandyer]

Hypothetical scenario:

I'm an admin who didn't get a chance to run the semi-automated upgrade prior to March 21.

It is now March 23 and I wish to upgrade, but my servers apparently aren't part of the batch that is receiving the rollout.

Am I safe to run the ./securedrop-admin noble_migration command? What will happen? When my "real" batch comes around, will it attempt the upgrade again or otherwise cause any breakage?

[legoktm]

Am I safe to run the ./securedrop-admin noble_migration command?

Yes.

What will happen?

The semi-automated upgrade will run as it normally does.

When my "real" batch comes around, will it attempt the upgrade again or otherwise cause any breakage?

Nope, once you're on noble, you're all set, the script won't do anything.

---

For technical context, https://github.com/freedomofpress/securedrop/blob/develop/securedrop/debian/config/usr/share/securedrop/noble-upgrade.json is the file that controls which upgrades should happen. The semi-automated upgrade works by overwriting this file to say "upgrade everything now" (https://github.com/freedomofpress/securedrop/blob/35e4b2df2b5c3197c605884e078adc6116cffc69/install_files/ansible-base/roles/noble-migration/tasks/main.yml#L13).

So even in the worst-case scenario race condition in which you server receives receives the fully automated instructions to begin the upgrade, and you manually initiate an upgrade at the same time, it'll just work because they use the same instruction file, and start the same systemd unit. (There is some small gotchas around how the ./securedrop-admin playbook expects to see exactly 2 reboots, so if the automated upgrade has already started, and it only sees one reboot, the playbook might hang, but the actual server upgrade will complete fine, and a second playbook run will succeed.

Or to look at it another way, the semi-automated way basically just starts the fully automatic upgrade and then waits for it to finish, so they can't really conflict.

[nathandyer]

Thanks @legoktm, that's excellent. I wanted to make sure that we didn't need to include any additional language to protect against running that command after the deadline. Since there's no harm in doing so, I think this PR is in good shape.

[nathandyer]

This PR LGTM. Leaving open for @cfm to review as well before merging.

[cfm]

Looks good! One non-blocking suggestion inline.