From b2461aca14a57bc1186a42722d911b582660097a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Tue, 12 Sep 2023 17:11:37 +0200 Subject: [PATCH 01/10] Write install guide --- INSTALL.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..105b17fd5 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,108 @@ +# Installing Ubuntu Pro For Windows + +- [Installing Ubuntu Pro For Windows](#installing-ubuntu-pro-for-windows) + - [Requirements](#requirements) + - [Download](#download) + - [Install the Windows agent](#install-the-windows-agent) + - [Install the WSL Pro Service](#install-the-wsl-pro-service) +- [Tests and utilities](#tests-and-utilities) + - [Enabling Pro](#enabling-pro) + - [Landscape registration](#landscape-registration) + +### 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_1.0.0.0_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 dpkg -i 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 https://ubuntu.com/pro/dashboard and 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 one in the example. +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. Windows Menu + 2. Search Ubuntu Pro For Windows + 3. The GUI should start + 4. Wait a minute + 5. 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 From bb199c952c170a47334e3b11e55c8489f8e2dadb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 09:59:35 +0200 Subject: [PATCH 02/10] Goodbye table of contents --- INSTALL.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 105b17fd5..527f417dc 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,14 +1,5 @@ # Installing Ubuntu Pro For Windows -- [Installing Ubuntu Pro For Windows](#installing-ubuntu-pro-for-windows) - - [Requirements](#requirements) - - [Download](#download) - - [Install the Windows agent](#install-the-windows-agent) - - [Install the WSL Pro Service](#install-the-wsl-pro-service) -- [Tests and utilities](#tests-and-utilities) - - [Enabling Pro](#enabling-pro) - - [Landscape registration](#landscape-registration) - ### Requirements - A Windows machine with access to the internet - Appx from the Microsoft Store: From 56be6511079ab01708c56b66d1a6cf088a473e46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:03:04 +0200 Subject: [PATCH 03/10] Better punctuation --- INSTALL.md | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 527f417dc..595b6bd2a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -10,17 +10,15 @@ ### 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 +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 +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" @@ -32,19 +30,19 @@ This is the Windows-side agent that manages the distros. ```powershell Add-AppxPackage .\UbuntuProForWindows_1.0.0.0_x64.msixbundle ``` -6. Open the start menu and search for Ubuntu Pro For Windows +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 +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 +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_* @@ -63,8 +61,8 @@ This is the Linux-side component that talks to the agent. Choose one or more dis If you’ve completed the installation, you may want to check that it worked. To do so, follow these steps: 1. Go to https://ubuntu.com/pro/dashboard and 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 +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 @@ -73,9 +71,9 @@ If you’ve completed the installation, you may want to check that it worked. To ## 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` +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 one in the example. @@ -85,13 +83,12 @@ You can use a private Landscape instance (different from [landscape.canonical.co ```powershell Get-Process -Name Ubuntu-Pro-Agent | Stop-Process ``` -8. Start the agent again - 1. Windows Menu - 2. Search Ubuntu Pro For Windows - 3. The GUI should start - 4. Wait a minute - 5. Click to restart it -9. Stop the distro you installed WSL-Pro-Service in. +8. Start the agent again: + 1. Open the start Menu and search 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 ``` From 30c70b37b5e3ab140a844196a510752cbae5c5f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:05:20 +0200 Subject: [PATCH 04/10] Better links --- INSTALL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 595b6bd2a..b368ab9b2 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -59,7 +59,7 @@ This is the Linux-side component that talks to the agent. Choose one or more dis # 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 https://ubuntu.com/pro/dashboard and get your Ubuntu Pro token +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". @@ -76,7 +76,7 @@ You can use a private Landscape instance (different from [landscape.canonical.co 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 one in the example. + - 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: From 974c12f8db1f349bffa4353c9dfa37ad2fca8f0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:06:30 +0200 Subject: [PATCH 05/10] Don't rely on a specific version of Windows Agent --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index b368ab9b2..4ff3d136e 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -28,7 +28,7 @@ This is the Windows-side agent that manages the distros. 4. Find the certificate inside. Install it into `Local Machine/Trusted people`. 5. Open Powershell in this directory and run ```powershell - Add-AppxPackage .\UbuntuProForWindows_1.0.0.0_x64.msixbundle + 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. From cacb4f603ff1fe24f71ddc78f7057c19d8016bee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:09:30 +0200 Subject: [PATCH 06/10] Use apt instead of dpkg --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 4ff3d136e..1b04f5289 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -49,7 +49,7 @@ This is the Linux-side component that talks to the agent. Choose one or more dis ``` 5. Install the deb package. ```bash - sudo dpkg -i wsl-pro-service_*.deb + sudo apt install ./wsl-pro-service_*.deb ``` 6. Ensure it works via systemd: ```bash From 58f04ecf19a0fb74d89374aee52c596293d92af2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:13:37 +0200 Subject: [PATCH 07/10] Use quotes for literal text --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 1b04f5289..f5ac8e193 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -61,7 +61,7 @@ This is the Linux-side component that talks to the agent. Choose one or more dis 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. +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 From 41e3d77ea668bd224b658835cfc23dc45950811a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 10:14:36 +0200 Subject: [PATCH 08/10] More quotes --- INSTALL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index f5ac8e193..22a9676a2 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -30,7 +30,7 @@ This is the Windows-side agent that manages the distros. ```powershell Add-AppxPackage .\UbuntuProForWindows_*_x64.msixbundle ``` -6. Open the start menu and search for Ubuntu Pro For Windows. +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. @@ -84,7 +84,7 @@ You can use a private Landscape instance (different from [landscape.canonical.co Get-Process -Name Ubuntu-Pro-Agent | Stop-Process ``` 8. Start the agent again: - 1. Open the start Menu and search Ubuntu Pro For Windows. + 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". From f2ac309891ce85147fe753b2372ea8568387606c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Wed, 13 Sep 2023 14:01:28 +0200 Subject: [PATCH 09/10] Move to docs folder This'll automatically replicate it in the Wiki --- INSTALL.md => doc/02.Installation.md | 1 + ...-reference.md => 03.-Windows-Agent-command-line-reference.md} | 0 ...eference.md => 04.-WSL-Pro-Service-command-line-reference.md} | 0 3 files changed, 1 insertion(+) rename INSTALL.md => doc/02.Installation.md (97%) rename doc/{2.-Windows-Agent-command-line-reference.md => 03.-Windows-Agent-command-line-reference.md} (100%) rename doc/{3.-WSL-Pro-Service-command-line-reference.md => 04.-WSL-Pro-Service-command-line-reference.md} (100%) diff --git a/INSTALL.md b/doc/02.Installation.md similarity index 97% rename from INSTALL.md rename to doc/02.Installation.md index 22a9676a2..c8c1bb08f 100644 --- a/INSTALL.md +++ b/doc/02.Installation.md @@ -1,4 +1,5 @@ # 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 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 From 5222d9f3de2bea004bc6b80600d9f9dfba626de5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20G=C3=B3mez=20Escandell?= Date: Thu, 14 Sep 2023 08:50:27 +0200 Subject: [PATCH 10/10] Add TODO regarding artifact hosting --- doc/02.Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/02.Installation.md b/doc/02.Installation.md index c8c1bb08f..90a715d45 100644 --- a/doc/02.Installation.md +++ b/doc/02.Installation.md @@ -9,7 +9,7 @@ This guide will show you how to install Ubuntu Pro For Windows for local develop - 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.