What is the correct way to install on Windows/WSL2?
joegl opened this issue · 5 comments
The documentation I've found is confusing to me on how to properly install Lando on Windows/WSL2.
https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html
This documentation says to use Hyperdrive? Hyperdrive seems abandoned and hasn't had a release since 2020 (4 years ago now). This "Setup Guide" also says to NOT use Docker desktop and to uninstall Docker Destop and your WSL2 installation first, and then reinstall WSL2. This guide doesn't really have any information on how to actually install Lando. This documentation says it was updated 2 weeks ago.
https://docs.lando.dev/install/windows.html
This documentation says to have WSL2 installed and run the .exe from the releases page. There's hardly any information on this page and doesn't mention anything about Docker desktop. It just says to go through the installation prompts. How exactly does this .exe install Lando? This documentation says it was updated 1 week ago.
https://docs.lando.dev/core/v3/performance.html
This documentation says to install Lando in a WSL Linux distribution and then links to this third-party guide which recommends installing docker desktop for Windows (the exact opposite of what the first linked documentation states). This documentation says it was updated 1 week ago.
What is exactly the best way to install Lando on Windows/WSL2? I'm confused and appreciate any help or suggestions and please excuse my potential ignorance.
Like @joegl, I found the contradictory messages about Lando installation for Windows confusing. The docs require a general cleanup to help new users understand what is actually current and recommended.
The first step I recommend would be to revise the windows.md page so that it is clear that there are TWO ways of installing under Windows:
https://docs.lando.dev/install/windows.html
Both methods require WSL2 to be enabled.
The 1st, easiest method for new users is to use the exe, after which users invoke Lando via a native Windows command shell, like Powershell.
The 2nd method installs Lando from within a WSL shell environment - like the Ubuntu default shell, which users then use to invoke Lando.
The MacOS installation docs have a "quickstart" cut-and-paste code, and then an "Advanced" section with more details.
Maybe for Windows, we can call the 1st the "recommended" or "easy" install, and then have the 2nd as an "Advanced".
In the "Advanced" section, we could include some notes on advantages (performance) and disadvantages (file system access, native software limitations) of the 2nd approach?
Good points! I think both https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html and the other guide linked by https://docs.lando.dev/core/v3/performance.html are out-of-date; I'm going to remove references to both of them (linking to the main Windows install instructions).
@pkiff once the Windows installer script is finished (see lando/setup-lando#17), the main install instructions should basically mirror the Mac ones. That script will install Lando across all available WSL2 instances, so it should allow the user to access it both from Powershell "natively" as well as within any of the WSL2 instances the user has set up.
Until then I think you're right; the two options are to either install via the .exe, or follow the Linux instructions on your WSL2 instance. What do you think of these revised instructions? lando/setup-lando#36
I'm excited to learn about the work on the new Windows installer script. Your edit in lando/setup-lando#36 looks good to me.
The revised instructions combined with removing references to old info I think resolve the issue #265 in this thread.
One thing that I stumbled over when I installed under WSL2 following the Linux instructions was that I needed to insert a different path in the command to trust the Lando certs - because I want to view the site in my browser from Windows, but serve the site up from lando, within WSL. Neither the Windows, nor the Linux instructions included a command that allowed me to open my site using https in my Windows browser:
https://docs.lando.dev/core/v3/security.html#certificates
I ended up following the instructions here:
https://tabernawp.com/en/relying-on-the-lando-certificate-from-wsl2-2023-03-01.html
But I think this tip probably belongs on the Security docs page, rather than in the getting started / setup Windows page. Or maybe it can somehow be included in the Windows installer script.
Nice, that's a good detail @pkiff: lando/core#151