Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat: Windows Native and WSL2 GUI installer#7404

Merged
rfay merged 19 commits into
ddev:mainfrom
rfay:20250625_rfay_wsl2_nsis_installer
Jul 11, 2025
Merged

feat: Windows Native and WSL2 GUI installer#7404
rfay merged 19 commits into
ddev:mainfrom
rfay:20250625_rfay_wsl2_nsis_installer

Conversation

@rfay
Copy link
Copy Markdown
Member

@rfay rfay commented Jun 26, 2025

The Issue

Related to

We've long had two pretty awkward PowerShell script that people needed to run to do basic WSL2 setup for DDEV. One was for docker-ce and the other for Docker Desktop. People struggled a bit with the instructions. With an installer we can give more guidance

How This PR Solves The Issue

This won't be ready for some time, and depends on other things that are in play. However, it currently builds an amd64 installer that does docker-ce, Docker Desktop, and works with Rancher Desktop

It could actually do the install for the traditional Windows as well.

TODO

  • Consider consolidating all Windows installs into one installer.
  • Add Rancher Desktop support to prompts in installer
  • Make sure that mkcert integration is working right for all. Can it be skipped if mkcert -install already run?
  • docs: Add Rancher Desktop limited support for WSL2
  • docs: Upgrade instructions (just run the installer)
  • docs: Add to manual install docs with instructions/suggestions for other distros. Improve docs in general.
  • installer: Add suggestion link if distro is not Ubuntu.
  • installer: Consider allowing them to choose which distro to install in, not requiring them to use the default distro.
  • Makefile needs to support amd64/arm64 installers (and sign both)
  • Do automated testing of the install (all 3 paths)
  • Make sure the recommends status of packages is as we want it. (and followup possibly create a wsl2 package)
  • Review the nsi file carefully again
  • Program Files directory should be properly specified, not defaulted to C drive
  • amd64 and arm64 architectures
  • Improve Makefile logic so it only builds the exe files it needs
  • How will Chocolatey work? Assume that it's doing regular Windows install...
  • Consider a better icon and art for the initial screen
  • WSL2 paths should install current WSL2 binary (and ddev-hostname) if possible
  • Verify that apt-get upgrade after the "hold" actually updates to a new version (we replaced the package-installed binary with a built one, but we want apt-get to update it)
  • Add check for git-bash on traditional windows
  • Installer should have a page that invites people to support DDEV

Manual Testing Instructions

  • Install fresh Ubuntu, make it default, test with docker-ce, test ddev there
  • Re-run installer on already installed Ubuntu, test ddev there. Verify that /etc/apt/sources.list.d entries are correct
  • Install fresh Ubuntu, make it default, Enable Docker Desktop integration on the distro, test with Docker Desktop install
  • Re-run installer with Docker Desktop setup, test ddev.
  • [ ]

Automated Testing Overview

Release/Deployment Notes

@rfay rfay changed the title feat: Windows WSL2 GUI installer feat: Windows WSL2 GUI installer [WIP] Jun 26, 2025
@rfay rfay force-pushed the 20250625_rfay_wsl2_nsis_installer branch 2 times, most recently from fe7fb1e to 4f6f273 Compare June 30, 2025 12:55
@rfay rfay changed the title feat: Windows WSL2 GUI installer [WIP] feat: Windows Native and WSL2 GUI installer [WIP] Jul 2, 2025
@rfay rfay force-pushed the 20250625_rfay_wsl2_nsis_installer branch from 8b07f08 to e59ba4f Compare July 2, 2025 21:46
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Jul 3, 2025

@rfay rfay requested a review from stasadev July 3, 2025 23:07
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 3, 2025

I know this has a ways to go @stasadev but I'm almost to writing tests for it, and would appreciate if you could take the installer for a bit of a run. There are many permutations... I have been often recreating distros like Ubuntu-20.04, Ubuntu-22.04, Ubuntu-24.04. My normal one is just "Ubuntu".

@rfay rfay force-pushed the 20250625_rfay_wsl2_nsis_installer branch from f205305 to 2c2eefd Compare July 4, 2025 18:01
Copy link
Copy Markdown
Member

@stasadev stasadev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WSL2 with Docker CE

No WSL2 found error is not fatal enough.
The installer gets stuck, but installs mkcert and files to C:\Program Files\DDEV
I expect that clicking Ok on error will either go back to install type selection or to close the installer.

no-wsl-found-1

WSL2 with Docker Desktop or Rancher Desktop

No WSL2 found error is not fatal enough.
The installer gets stuck, but installs mkcert and files to C:\Program Files\DDEV
I expect that clicking Ok on error will either go back to install type selection or to close the installer.

no-wsl-found-2

Traditional Windows

Docker provider check is too late and not fatal enough.
The installer gets stuck, but installs mkcert and files to C:\Program Files\DDEV, and only then shows error for Docker provider.
I expect that this check is done before mkcert and copying files.
I expect that clicking Ok on error will either go back to install type selection or to close the installer.

no-docker-provider-found

Comment thread winpkg/ddev_windows_installer.nsi Outdated
Comment thread winpkg/ddev_windows_installer.nsi Outdated
Pop $1
Pop $0
${If} $1 != 0
MessageBox MB_ICONSTOP|MB_OK "Failed to install dependencies. Please check the logs."
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's unclear what logs I need to check:
1

I think it's better to show error details like it's done here:
2

Comment thread winpkg/ddev_windows_installer.nsi Outdated
Comment on lines +589 to +1057
; apt-get upgrade
DetailPrint "WSL($SELECTED_DISTRO): Doing apt-get upgrade..."
nsExec::ExecToStack 'wsl -d $SELECTED_DISTRO -u root bash -c "apt-get update && apt-get upgrade -y >/dev/null 2>&1"'
Pop $1
Pop $0
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of these apt-get calls need MessageBox with error details.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

Comment thread mkdocs.yml
@rfay rfay force-pushed the 20250625_rfay_wsl2_nsis_installer branch from 8096a7b to 97f0dc7 Compare July 6, 2025 22:12
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 7, 2025

No WSL2 found error is not fatal enough.

I tried this again with current code (wsl --uninstall and then try WSL2 installer). It was close to adequate. (Fix system with prompted wsl --update and I didn't lose any distros)

Fatal missing docker provider

On Docker Desktop/WSL2:

image

On Traditional Windows:

image

@stasadev stasadev self-requested a review July 7, 2025 13:54
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 8, 2025

Added check for git-bash/git
Improved experience when bash or docker desktop not available.
Has useful automated tests for all three approaches. The problem is they have to be escalated to run, so that's another hurdle.

@rfay rfay marked this pull request as ready for review July 8, 2025 01:03
@rfay rfay requested review from a team as code owners July 8, 2025 01:03
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 8, 2025

Running as "local service account", fully privileged:

gsudo nssm set buildkite-agent AppEnvironmentExtra "HOME=C:\buildkite-agent"

Restart service.

Now we have to figure out how to get this agent to pick up this type of test.

I set up tb-win11-10 to run as "local service account". And https://buildkite.com/ddev/ddev-windows-mutagen/builds/5311 is running

@rfay rfay changed the title feat: Windows Native and WSL2 GUI installer [WIP] feat: Windows Native and WSL2 GUI installer Jul 8, 2025
@rfay rfay requested a review from tyler36 July 8, 2025 17:48
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 8, 2025

@tyler36 if you could try out as much of the installer as you're willing it would be very welcome. You can use additional WSL2 distros, it doesn't have to touch your normal distro that you use.

@colans
Copy link
Copy Markdown
Contributor

colans commented Jul 8, 2025

@rfay: Is there another place to get the installer? https://nightly.link/ seems blocked over here.

@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 8, 2025

HeidiSQL has a decent installer finish page:

image

@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 8, 2025

Happy to get it for you any way you like @colans , and thanks! What works for you? Dropbox? Google?

@colans
Copy link
Copy Markdown
Contributor

colans commented Jul 8, 2025

Maybe just upload it here somewhere as GitHub works (just in a comment is fine if there's no better place).

Copy link
Copy Markdown
Collaborator

@tyler36 tyler36 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Unknown publisher

DDEV comes up as "unknown publisher" on this and the UAC pop up. Ideally, this should be "DDEV Foundation" (official brand?), but not sure how difficult or time/cost involed.

Image
  1. Ubuntu only

Correctly detected my 3 Ubuntu WSL distrobutions but not Alpine, Amazon, CentOS, Debian, Fedora, OpenSUSE, RedHat or Rocky WSLs.
Update: Oh, it's not detecting Ubuntu WSL's, it's checking a WSL's name contains "Ubuntu" (case-insenitive). I added a new WSL called 'foobar' that it didn't detect, but it detected "ubuntu-foobar".

  1. Non-default, no Docker Desktop intergration
  • Detected non-default Ubuntu WSL did NOT have Docker Desktop intergration turned on. Suggested I turn on DD (or rancher) then activate intergration.
  • After activing DD WSL intergation, it correctly detected and continued installation.
  1. "WSL(ubuntu-foobar): Doing apt-get upgrade..."

I know apt-get can take a while sometimes, but it looks busy in my terminal. When using the DDEV installing, there's no "activity indicator" so it "feels" like it's frozen. Perhaps a message on the previous screen, "Installing WSL components may take a couple of minutes. "

  1. Root user.

Forgot to update my login so I was set as root. Got the following message:

  • Couple of ANSI escape codes that could be cleaned up
Image
  • Text says to click "Show details" but only see "OK". Clicked "OK"
    No "Show details" here either. Clicking "Cancel" exists installer.
Image

@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 9, 2025

Thanks @tyler36 - The "Unknown publisher" is because you're using the unsigned PR build. I can push the same thing to ddev-test and get it signed, but this is a fine thing.

"Ubuntu-only": We don't know how to select distros except by name. Other suggestions are welcome. I did look into explicitly supporting Debian as well, but it's already too complicated (on the code side)

Text says to click "Show details" but only see "OK". Clicked "OK"
No "Show details" here either

In that screenshot you're showing details, so that's why the "Show details" button doesn't show.

"Root user": It checks for that and complains early, so you shouldn't have gotten to that point. Could you do that again and see if you can give an exact repro path?

@tyler36
Copy link
Copy Markdown
Collaborator

tyler36 commented Jul 9, 2025

  1. "Programs and Features" / Uninstalling

Control Panel\All Control Panel Items\Programs and Features

  • Icon appears fuzzy/low quality
  • Size is not reported
  • Uninstalling appears to remove mkcert but not DDEV from WSL.
    image

@rfay rfay requested a review from tyler36 July 11, 2025 01:32
@rfay rfay force-pushed the 20250625_rfay_wsl2_nsis_installer branch from 7b2e3b3 to 25ca885 Compare July 11, 2025 01:33
Comment thread winpkg/ddev_windows_installer.nsi Outdated
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 11, 2025

It’s probably best to recommend that users uninstall DDEV via "Add or Remove Programs" before installing the new version, since ddev.exe on the Windows side is not removed. This could be mentioned in the release notes.

I'm not convinced that it's important to remove the ddev.exe, and it adds complexity to bother people with this. It could (maybe?) also mess with their mkcert config to uninstall.

@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 11, 2025

The installer now remembers the install type and distro that were previously chosen and uses those as default. Removed the checkmark from the final page. Reworked the distro radio boxes as dynamic instead of stupid. Probably needs a little more casual manual testing.

@rfay rfay requested a review from stasadev July 11, 2025 14:05
@rfay
Copy link
Copy Markdown
Member Author

rfay commented Jul 11, 2025

Broke the apt-get install into 4 parts so people get feedback that something is happening. Updated signed release in https://github.com/ddev-test/ddev/releases/tag/v1.99.8 (or just see latest release there)

Copy link
Copy Markdown
Member

@stasadev stasadev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome!

Installation type and distro selection was saved.
Splitting apt-get in parts is a good idea.
And the Support checkbox looks good.

Comment thread winpkg/ddev_windows_installer.nsi Outdated
Co-authored-by: Stanislav Zhuk <[email protected]>
@rfay rfay merged commit 4416924 into ddev:main Jul 11, 2025
12 of 17 checks passed
@rfay rfay deleted the 20250625_rfay_wsl2_nsis_installer branch July 11, 2025 22:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants