diff --git a/doc/02.Installation.md b/doc/02.Installation.md new file mode 100644 index 000000000..90a715d45 --- /dev/null +++ b/doc/02.Installation.md @@ -0,0 +1,97 @@ +# Installing Ubuntu Pro For Windows +This guide will show you how to install Ubuntu Pro For Windows for local development and testing. + +### Requirements +- A Windows machine with access to the internet +- Appx from the Microsoft Store: + - Windows Subsystem For Linux + - Either Ubuntu, Ubuntu 22.04, or Ubuntu (Preview) +- The Windows Subsystem for Windows optional feature enabled + +### Download + +1. Go to the [repository actions page](https://github.com/canonical/ubuntu-pro-for-windows/actions/workflows/qa.yaml?query=branch%3Amain+). +2. Click the latest successful workflow run. +3. Scroll down past any warnings or errors, until you reach the Artifacts section. +4. Download: + - Windows agent: UbuntuProForWindows+... + - WSL-Pro-Service: Wsl-pro-service_… + +### Install the Windows agent +This is the Windows-side agent that manages the distros. +1. Uninstall Ubuntu Pro For Windows if you had installed previously: + ```powershell + Get-AppxPackage -Name Ubuntu-Pro-For-Windows | Remove-AppxPackage + Remove-Item -Recurse "${env:LOCALAPPDATA}/Ubuntu Pro" + ``` +2. Follow the download steps to download UbuntuProForWindows +3. Unzip the artifact +4. Find the certificate inside. Install it into `Local Machine/Trusted people`. +5. Open Powershell in this directory and run + ```powershell + Add-AppxPackage .\UbuntuProForWindows_*_x64.msixbundle + ``` +6. Open the start menu and search for "Ubuntu Pro For Windows". +7. The Firewall may ask for an exception. Allow it. +8. The GUI should show up. You’re done. + + +### Install the WSL Pro Service +This is the Linux-side component that talks to the agent. Choose one or more distros Jammy or greater, and follow the instructions. +1. Uninstall the WSL-Pro-Service from your distro if you had it installed previously: + ```bash + sudo apt remove wsl-pro-service + ``` +2. Follow the download steps to download the WSL-Pro-Service. +3. Unzip the artifact. +4. Navigate to the unzipped directory containing the .deb file. Here is a possible path: + ```bash + cd /mnt/c/Users/WINDOWS-USER/Downloads/wsl-pro-service_* + ``` +5. Install the deb package. + ```bash + sudo apt install ./wsl-pro-service_*.deb + ``` +6. Ensure it works via systemd: + ```bash + systemctl status wsl-pro.service + ``` + +# Tests and utilities +## Enabling Pro +If you’ve completed the installation, you may want to check that it worked. To do so, follow these steps: +1. Go to your [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboardand) to get your Ubuntu Pro token. +2. Go to the Windows menu, and search and click Ubuntu Pro For Windows. If it does not show up, your installation of the agent went wrong. +3. Click on "I already have a token". +4. Introduce the token you got from your Pro dashboard, and click "Apply". +5. Start the distro you installed WSL-Pro-Service in, and run + ```bash + pro status + ``` +6. If the distro is pro-attached, the installation was successful. + +## Landscape registration +You can use a private Landscape instance (different from [landscape.canonical.com](landscape.canonical.com)). It must be over HTTP, as using certificates is not yet supported. To do so, follow these steps: +1. Press Windows+R. +2. Write regedit.exe and enter. +3. Go to `HKEY_CURRENT_USER\Software\Canonical\UbuntuPro`. +4. There are two relevant fields: + - LandscapeAgentURL should contain the URL where the Landscape Hostagent server is hosted. + - LandscapeClientConfig should contain the contents of the yaml file with the settings, such as the [example from the Landscape repository](https://github.com/canonical/landscape-client/blob/master/example.conf). +5. To edit any of the fields, right-click and Edit +6. If you need more than one line, delete the field and create a new one with the same name, and type `Multi-String Value`. +7. Stop the agent: + ```powershell + Get-Process -Name Ubuntu-Pro-Agent | Stop-Process + ``` +8. Start the agent again: + 1. Open the start Menu and search for "Ubuntu Pro For Windows". + 2. The GUI should start. + 3. Wait a minute. + 4. Click on "Click to restart it". +9. Stop the distro you installed WSL-Pro-Service in: + ```powershell + wsl --terminate DISTRO_NAME + ``` +10. Start the distro you installed WSL-Pro-Service in. +11. You should see a new "pending computer authorisation" in you Landscape dashboard. \ No newline at end of file diff --git a/doc/2.-Windows-Agent-command-line-reference.md b/doc/03.-Windows-Agent-command-line-reference.md similarity index 100% rename from doc/2.-Windows-Agent-command-line-reference.md rename to doc/03.-Windows-Agent-command-line-reference.md diff --git a/doc/3.-WSL-Pro-Service-command-line-reference.md b/doc/04.-WSL-Pro-Service-command-line-reference.md similarity index 100% rename from doc/3.-WSL-Pro-Service-command-line-reference.md rename to doc/04.-WSL-Pro-Service-command-line-reference.md