Linux setup experience

[noahtalerman]

Goal

User story
As an IT admin,
I want to install software during new Linux setup and show progress to my end user
so that I can make sure Linux workstations have the required software before a new employee starts working.

Roadmap item

👔 Customize first-time Windows and Linux setup

Original requests

• Linux setup experience #27898

Context

• Product Designer: @rachaelshaw

• Engineer: @dantecatalfamo

• @noahtalerman: During drafting, let's include wireframes for not letting users through on Linux. macOS story: macOS setup experience: if critical software fails, don't let end user through #30117

  • UPDATE: @noahtalerman: Wires for not letting users through on macOS, Windows, and Linux will be part of this story:
    • macOS setup experience: if critical software fails, don't let end user through #30117

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes
• YAML changes:
  • Allow setting setup_experience for Linux packages. See [YAML design] GitOps: Setup experience, custom targets (labels), self-service, & categories for all software in team YAML #30837 for details.
• REST API changes: PR
  • Add platform parameter (defaults to "macos")
• Fleet's agent (fleetd) changes: No changes
• GitOps Mode UI changes: No changes
  • Add software button gets disabled in GitOps mode (same as macOS)
• GitOps generation changes: No changes
• Activity changes: Draft PR
• Permissions changes: PR
• Changes to paid features or tiers: Fleet Premium
• My device and fleetdm.com/better changes: No changes
• Other reference documentation changes: TODO: check for docs that specifically mention macOS setup experience and see if it makes sense to change to "macOS and Linux"
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: TODO
• Feature guide changes:
  • Document best practice: the Linux image you're using should include a browser (otherwise the end user won't see the install progress)
  • Document that the best practice is to install fleetd using an autoinstall.yml file as part of the Linux image.
    • Customers are already using and autoinstall.yml. Here's an example. Let's document this for other customers (and ourselves) who are new to Linux.
  • When fleetd is uninstalled and and re-installed, setup experience happens again. How? Fleet touches a file on the machine that says setup happened. If The IT admin is testing Linux setup experience, they can remove the file. The next time the host checks in to Fleet, setup experience will happen again.

• Database schema migrations: TODO
• Load testing: TODO

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires load testing: TODO
• Risk level: Low / High TODO
• Risk description: TODO

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

1. Test other setup experience tabs:
   • macOS
     • Make sure old setup experience links redirect to the right section of the macOS tab
     • Verify UI changes to add software modal
     • Copy changes
   • Windows
2. Test Linux setup experience UI states with different software configurations:
   • No software available to add
   • No software added
3. Add software to Linux setup experience.
   • Verify modal UI and the UI state changes on the page once the software has been saved
4. Test adding Linux setup experience software via GitOps
   • Also try adding incompatible software
5. Try adding Linux setup experience software via the API
6. Test setup experience install software API for macOS, both with platform empty and with platform field set to "macos"
7. Test setup experience install software API with platform set to "windows" - should get an error
8. Test end user experience + Make sure browser window pops open when Fleed Desktop starts running
   • Make sure proper loading/completed states appear as installs are completed
   • Make sure the page reloads when all setup is completed
9. Add software to setup experience that will cause an error. Test end user experience.
   • Make sure it shows as "Failed"
10. Add a package for a different flavor of Linux. Make sure it does not appear in end user experience when not compatible.
11. Test end user experience without a browser installed.
    • Software should still install

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.

[noahtalerman]

@rachaelshaw just showed this @mike-j-thomas. He had no context and his initial assumption was the icon makes it look like there's an issue with the software:

I think let's use our generic package icon instead for now:

[noahtalerman]

• @noahtalerman: During drafting, let's include wireframes for not letting users through on Linux. macOS story: macOS setup experience: if critical software fails, don't let end user through #30117
  • UPDATE: @noahtalerman: Wires for not letting users through on macOS, Windows, and Linux will be part of this story:
    • macOS setup experience: if critical software fails, don't let end user through #30117

FYI @rachaelshaw

[noahtalerman]

@rachaelshaw I made some tweaks during my async review:

Version column instead of "Platform". I think in this view, it's valuable to tell the IT admin what version is going to get installed:

Version column for Linux includes the package extension:

Added this dev note. We haven't made this change yet (I think):

Added this dev note:

Added copy explaining "when" the end users sees the selected software. I think it's important to be explicit about exactly when this happens to set IT admin expectations:

Please feel free to add tweaks on top of mine!