Update Install Guide for 4.2 #228

nathandyer · 2024-07-09T19:26:10Z

This PR updates the install guide to reference all the changes users will now encounter as they step through an installation using Qubes 4.2. While most of these changes a fairly straightforward (for example, updating the locations of items inside the Qubes menu), a few of the changes I've made should be made explicit here:

I've added a warning to the top of the prepare and install pages noting that not all packages are available in the repos, and that these instructions will not work until that happens. We should remove this once 1.0.0 is released and packages are available on yum.securedrop.org.
Likewise, there are links to the Qubes 4.2.2-rc1 iso (mainly as a placeholder) that need to be updated to stable 4.2.2 once that is ready.
I removed the Fedora 40 upgrade guide, and the references to it within; from here forward, no Workstation users will encounter a situation where they would need to manually upgrade to the Fedora 40 template.
I've expanded the docs in a few small ways, such as noting that the "Unable to unlock 'TailsData'" warning is to be expected, and to make it explicit how to easily verify the Qubes ISO

Testing

Visual review
CI passes

legoktm

Flagged a few things. Per discussion let's change the Qubes URLs to point to a future 4.2.2 release, if it's not ready by the time we go stable we can change it down to 4.2.1 and restore the upgrade Fedora instructions.

Erik had a few more things in #222, do you want to cherry-pick those here too?

legoktm · 2024-07-10T21:10:06Z

docs/admin/install/install.rst

@@ -76,9 +83,9 @@ Users of SecureDrop Workstation must enter their username, passphrase and two-fa

 In order to set up KeePassXC for easy use:

- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Domain: vault > vault: Qube Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
+- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Apps > vault > Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).


This is a pre-existing issue, but "Applications" is part of a separate menu, and I think it's misleading to make it think it's part of the same Q menu.

(Not asking for a fix, just flagging for a future potential improvement)

I would vote to fix it while we're in here!

docs/admin/install/install.rst

docs/admin/install/prepare.rst

docs/admin/install/install.rst

zenmonkeykstop · 2024-07-10T23:23:32Z

docs/admin/install/install.rst

  |Unlock TailsData|

- Open a ``dom0`` terminal via **Q > Terminal Emulator**, and run the following command to list the SVS submission key details, including its fingerprint:
+- Open a ``dom0`` terminal via **Q > Settings Gear > Other > Xfce Terminal**, and run the following command to list the SVS submission key details, including its fingerprint:


If we can't have the gear icon specifically, this should read something like "Open the Q menu, select the gear icon on the left-hand side, and select Other > XFCE terminal to open a terminal in dom0"

I don't think we need to be that verbose, "Settings Gear" seems pretty clear to me?

How about ⚙️ ?

Whoops. Never mind. I see that that's what's being proposed already.

It is unlikely to be clear to everybody - some folk will take it literally and look for a text menu item, some folk may not be clear as to which settings gear it means (another one literally labeled "Settings" is shown on the left, that applies to single VMs). Specificity is worth it in this case even if it means being a little more verbose.

Would **Q > Settings Gear (left sidebar) > Other > Xfce Terminal** be sufficient?

Kev also mentioned that when you open the Q menu, there are two settings gears, one in the left sidebar, and one on the right side, as the "Settings" for whichever AppVM is selected by default, so we do need to disambiguate them somehow.

Thanks @zenmonkeykstop - that makes sense. I just pushed a change that should incorporate your suggestion everywhere the gear icon is mentioned. Reviewers, please make sure I didn't miss any.

zenmonkeykstop · 2024-07-10T23:23:59Z

docs/admin/install/install.rst

@@ -76,9 +83,9 @@ Users of SecureDrop Workstation must enter their username, passphrase and two-fa

 In order to set up KeePassXC for easy use:

- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Domain: vault > vault: Qube Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).
+- Add KeePassXC to the application menu by selecting it from the list of available apps in **Q > Apps > vault > Settings > Applications** and pressing the button labeled **>** (do not press the button labeled **>>**, which will add *all* applications to the menu).


I would vote to fix it while we're in here!

docs/admin/install/prepare.rst

zenmonkeykstop · 2024-07-10T23:28:08Z

docs/admin/install/prepare.rst

@@ -89,7 +122,7 @@ Once the initial setup is complete, the login dialog will be displayed. Log in u

 If, during the installation, you encountered the grayed out option "USB qube configuration disabled", you must now create a VM to access your USB devices. If you did not encounter this issue, you can skip this section.

-To create a USB qube, open a ``dom0`` terminal via the Qubes menu (the **Q** icon in the upper left corner): **Q > Terminal Emulator**. Run the following command:
+To create a USB qube, open a ``dom0`` terminal via the Qubes menu (the **Q** icon in the upper left corner): **Q > Settings Gear > Other > Xfce Terminal**. Run the following command:


Same note re gear icon.

docs/admin/install/prepare.rst

deeplow · 2024-07-11T14:17:33Z

docs/admin/install/prepare.rst

-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-See :doc:`../reference/upgrading_fedora`.
+- Once Tor has connected, select **Q > Settings Gear > Qubes Tools > Qubes Update** to update the system VMs. in the ``[Dom0] Qubes Updater`` window, check all entries in the list above except for dom0 (which you have already updated in the previous step). Then, click **Next**. The system's VMs will be updated sequentially - this may take some time. When the updates are complete, click **Finish**.


Does it still make sense to separate dom0 updating from template updating? Might be easier to suggest: check all boxes and restart afterwards. What to you think? This is already the case for how SDW updater works. So I can't think of any reason not to do it. On top of that, that would make all of this step GUI-based.

deeplow · 2024-07-11T19:18:25Z

docs/admin/install/install.rst

  |Unlock TailsData|

- Open a ``dom0`` terminal via **Q > Terminal Emulator**, and run the following command to list the SVS submission key details, including its fingerprint:
+- Open a ``dom0`` terminal via **Q > Settings Gear > Other > Xfce Terminal**, and run the following command to list the SVS submission key details, including its fingerprint:


How about ⚙️ ?

nathandyer · 2024-07-11T22:30:59Z

Alright, I think I've addressed everyone's feedback. If I've overlooked anything, please let me know. A rough list of changes I made:

Removed the warning and all language about pre-release/unstable software
Updated Qubes references to point to 4.2.2 (not rc), with the knowledge we can fall back to 4.2.1 if need be
Added in the additional changes from Erik's draft PR in Qubes 4.2 download, menu and updater changes #222
Added a commit to remove the section about rotating legacy passphrases (we can drop the commit if we want to leave that in for now)
It seems there is still some debate about how to handle the "Settings gear" references. The unicode icon is not an option for this release, and I think like @legoktm I prefer the more concise option of just referring to the "Settings gear icon" within the path - but will be glad to change it to the more verbose option ("on the left sidebar"... etc.) if we prefer it.

legoktm · 2024-07-12T15:27:03Z

I'm going to walk through this via yum-qa/apt-qa and approve if it all goes well.

docs/admin/install/prepare.rst

docs/admin/install/install.rst

legoktm

OK, finished going through, just about everything is good, I flagged one of the "Other locations" needing to be updated for Thunar, there are a few more places if you search in the file for it.

nathandyer · 2024-07-12T18:49:21Z

Thanks for taking the new instructions for such a thorough test drive @legoktm! Back to you.

legoktm

Awesome!

legoktm self-assigned this Jul 10, 2024

legoktm requested changes Jul 10, 2024

View reviewed changes

nathandyer force-pushed the qubes-42-install-changes branch from fa217d4 to ba30e96 Compare July 10, 2024 22:18

zenmonkeykstop requested changes Jul 10, 2024

View reviewed changes

deeplow reviewed Jul 11, 2024

View reviewed changes

nathandyer force-pushed the qubes-42-install-changes branch from ba30e96 to 36962ad Compare July 11, 2024 22:23

legoktm reviewed Jul 12, 2024

View reviewed changes

docs/admin/install/prepare.rst Outdated Show resolved Hide resolved

legoktm reviewed Jul 12, 2024

View reviewed changes

docs/admin/install/install.rst Outdated Show resolved Hide resolved

legoktm reviewed Jul 12, 2024

View reviewed changes

docs/admin/install/install.rst Show resolved Hide resolved

legoktm reviewed Jul 12, 2024

View reviewed changes

docs/admin/install/install.rst Show resolved Hide resolved

legoktm requested changes Jul 12, 2024

View reviewed changes

nathandyer force-pushed the qubes-42-install-changes branch from 36962ad to 98db13e Compare July 12, 2024 18:46

nathandyer force-pushed the qubes-42-install-changes branch from 98db13e to 33ec231 Compare July 12, 2024 18:54

legoktm previously approved these changes Jul 12, 2024

View reviewed changes

legoktm enabled auto-merge July 12, 2024 18:55

legoktm requested a review from zenmonkeykstop July 12, 2024 19:32

nathandyer added 2 commits July 12, 2024 16:07

Update install guide for 4.2

ecaa5d4

Remove legacy passphrase rotation section

e0adfb4

nathandyer dismissed legoktm’s stale review via e0adfb4 July 12, 2024 20:07

nathandyer force-pushed the qubes-42-install-changes branch from 33ec231 to e0adfb4 Compare July 12, 2024 20:07

zenmonkeykstop approved these changes Jul 12, 2024

View reviewed changes

legoktm added this pull request to the merge queue Jul 12, 2024

Merged via the queue into main with commit 6d5161a Jul 12, 2024
4 checks passed

legoktm deleted the qubes-42-install-changes branch July 12, 2024 20:32

deeplow mentioned this pull request Jul 15, 2024

Check ISO matches .DIGESTS #239

Merged

eloquence mentioned this pull request Jul 22, 2024

Qubes 4.2 download, menu and updater changes #222

Closed

This was referenced Jul 22, 2024

Fedora 39 upgrade docs should be removed #237

Closed

Fix a few menu invocations & dark mode issue #250

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Install Guide for 4.2 #228

Update Install Guide for 4.2 #228

nathandyer commented Jul 9, 2024

legoktm left a comment

legoktm Jul 10, 2024

zenmonkeykstop Jul 10, 2024

zenmonkeykstop Jul 10, 2024

legoktm Jul 11, 2024

deeplow Jul 11, 2024

deeplow Jul 11, 2024 •

edited

Loading

zenmonkeykstop Jul 12, 2024

legoktm Jul 12, 2024

legoktm Jul 12, 2024

nathandyer Jul 12, 2024

zenmonkeykstop Jul 10, 2024

zenmonkeykstop Jul 10, 2024

deeplow Jul 11, 2024

deeplow Jul 11, 2024

nathandyer commented Jul 11, 2024

legoktm commented Jul 12, 2024

legoktm left a comment

nathandyer commented Jul 12, 2024

legoktm left a comment

Update Install Guide for 4.2 #228

Update Install Guide for 4.2 #228

Conversation

nathandyer commented Jul 9, 2024

Testing

legoktm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deeplow Jul 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nathandyer commented Jul 11, 2024

legoktm commented Jul 12, 2024

legoktm left a comment

Choose a reason for hiding this comment

nathandyer commented Jul 12, 2024

legoktm left a comment

Choose a reason for hiding this comment

deeplow Jul 11, 2024 •

edited

Loading