Skip to content

Commit b79e2a0

Browse files
edibotopicedibotopic
authored
Merge pull request #156 from canonical/wsl-add-distro-ref-and-new-tutorial
adds files for new WSL issues
2 parents 5671a93 + 56f042c commit b79e2a0

File tree

2 files changed

+242
-0
lines changed

2 files changed

+242
-0
lines changed

‎wsl/reference/distributions.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Distributions
2+
3+
Our flagship distribution is Ubuntu. This is the one that is installed by default when you install WSL for the first time. However, we develop several flavours. It may be the case that one or more of these flavours fits your needs better.
4+
5+
Each of these flavours corresponds to a different application on the Microsoft Store, and once installed, they'll create different distros in your WSL. These are the applications we develop and maintain:
6+
7+
- [Ubuntu](https://apps.microsoft.com/detail/9PDXGNCFSCZV?hl=en-us&gl=US) ships the latest stable LTS release of Ubuntu. When new LTS versions are released, Ubuntu can be upgraded once the first point release is available.
8+
- [Ubuntu 18.04.6 LTS](https://apps.microsoft.com/detail/9PNKSF5ZN4SW?hl=en-us&gl=US), [Ubuntu 20.04.6 LTS](https://apps.microsoft.com/detail/9MTTCL66CPXJ?hl=en-us&gl=US), and [Ubuntu 22.04.3 LTS](https://apps.microsoft.com/detail/9PN20MSR04DW?hl=en-us&gl=US) are the LTS versions of Ubuntu and receive updates for five years. Upgrades to future LTS releases will not be proposed.
9+
- [Ubuntu (Preview)](https://apps.microsoft.com/detail/9P7BDVKVNXZ6?hl=en-us&gl=US) is a daily build of the latest development version of Ubuntu previewing new features as they are developed. It does not receive the same level of QA as stable releases and should not be used for production workloads.
10+
11+
## Naming
12+
13+
Due to different limitations in different contexts, these applications will have different names in different contexts. Here is a table matching them.
14+
15+
1. App name is the name you'll see in the Microsoft Store and Winget.
16+
2. AppxPackage is the name you'll see in `Get-AppxPackage`.
17+
3. Distro name is the name you'll see when doing `wsl -l -v` or `wsl -l --online`.
18+
4. Executable is the program you need to run to start the distro.
19+
20+
| App name | AppxPackage name | Distro name | Executable |
21+
| -------------------- | -------------------------------------- | ---------------- | ------------------- |
22+
| `Ubuntu` | `CanonicalGroupLimited.Ubuntu` | `Ubuntu` | `ubuntu.exe` |
23+
| `Ubuntu (Preview)` | `CanonicalGroupLimited.UbuntuPreview` | `Ubuntu-Preview` | `ubuntupreview.exe` |
24+
| `Ubuntu XX.YY.Z LTS` | `CanonicalGroupLimited.UbuntuXX.YYLTS` | `Ubuntu-XX.YY` | `ubuntuXXYY.exe` |

‎wsl/tutorial/develop-with-ubuntu-wsl.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Develop with Ubuntu on WSL
2+
3+
The easiest way to access your Ubuntu development environment in WSL is by using Visual Studio Code via the built-in `Remote` extension.
4+
5+
## What you will learn
6+
7+
* How to install WSL and Ubuntu on WSL from the terminal
8+
* How to set up Visual Studio Code for remote development with Ubuntu on WSL
9+
* How to create a basic Node.js webserver on Ubuntu using Visual Studio Code
10+
* How to preview HTML served from an Ubuntu WSL instance in a native browser on Windows
11+
12+
## What you will need
13+
14+
* A PC with Windows 10 or 11
15+
16+
## Install Ubuntu on WSL2
17+
18+
### Install WSL
19+
20+
Open a PowerShell prompt as an Administrator and run:
21+
22+
```{code-block} text
23+
> wsl --install
24+
```
25+
26+
This command will enable the features necessary to run WSL and also install the latest Ubuntu distribution available for WSL. It is recommended to reboot your machine after this initial installation to complete the setup.
27+
28+
### Install Ubuntu on WSL
29+
30+
WSL supports a variety of Ubuntu releases. Check our [reference on the distributions](https://documentation.ubuntu.com/wsl/en/latest/reference/distributions/) for more information.
31+
32+
There are multiple ways of installing Ubuntu on WSL, here we focus on using the terminal.
33+
For other installation methods, refer to your dedicated guide:
34+
35+
* [Install Ubuntu on WSL2](https://documentation.ubuntu.com/wsl/en/latest/guides/install-ubuntu-wsl2/)
36+
37+
In a PowerShell terminal, run `wsl --list --online` to see all available distros and versions:
38+
39+
```{code-block} text
40+
The following is a list of valid distributions that can be installed.
41+
The default distribution is denoted by '*'.
42+
Install using 'wsl --install -d <Distro>'.
43+
44+
NAME FRIENDLY NAME
45+
* Ubuntu Ubuntu
46+
Debian Debian GNU/Linux
47+
kali-linux Kali Linux Rolling
48+
Ubuntu-18.04 Ubuntu 18.04 LTS
49+
Ubuntu-20.04 Ubuntu 20.04 LTS
50+
Ubuntu-22.04 Ubuntu 22.04 LTS
51+
Ubuntu-24.04 Ubuntu 24.04 LTS
52+
...
53+
54+
```
55+
56+
Your list may be different once new distributions become available.
57+
58+
You can install a version using a NAME from the output, for example:
59+
60+
```{code-block} text
61+
> wsl --install -d Ubuntu-24.04
62+
```
63+
64+
You'll see an indicator of the installation progress in the terminal:
65+
66+
```{code-block} text
67+
Installing: Ubuntu 24.04 LTS
68+
[==========================72,0%========== ]
69+
```
70+
71+
Use `wsl -l -v` to see all your currently installed distros and the version of WSL they are using:
72+
73+
```{code-block} text
74+
NAME STATE VERSION
75+
Ubuntu-20.04 Stopped 2
76+
* Ubuntu-24.04 Stopped 2
77+
```
78+
79+
## Install Visual Studio Code on Windows
80+
81+
One of the advantages of WSL is that it can interact with the native Windows version of Visual Studio Code using its remote development extension.
82+
83+
To install Visual Studio Code, visit the Microsoft Store and search for Visual Studio Code.
84+
85+
Then click **Install**.
86+
87+
![Installation page for Visual Studio Code on the Microsoft Store.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/msstore.png?raw=true)
88+
89+
Alternatively, you can install Visual Studio Code from the web link [here](https://code.visualstudio.com/Download).
90+
91+
![Visual Studio Code download page showing download options for Windows, Linux, and Mac.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/download-vs-code.png?raw=true)
92+
93+
During installation, under the 'Additional Tasks' step, ensure the `Add to PATH` option is checked.
94+
95+
![Visual Studio Code's "Additional Tasks" setup dialog with the "Add to Path" and "Register Code as an editor for supported file types" options checked.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/aditional-tasks.png?raw=true)
96+
97+
Once the installation is complete, open Visual Studio Code.
98+
99+
## Install the Remote Development Extension
100+
101+
Navigate to the `Extensions` menu in the sidebar and search for `Remote Development`.
102+
103+
This is an extension pack that allows you to open any folder in a container, remote machine, or in WSL. Alternatively, you can just install `Remote - WSL`.
104+
105+
![Installation page for the Remote Development Visual Studio Code extension.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/remote-extension.png?raw=true)
106+
107+
Once installed we can test it out by creating an example local web server with Node.js
108+
109+
## Install Node.js and create a new project
110+
111+
Open your WSL Ubuntu terminal and ensure everything is up to date by typing:
112+
113+
```{code-block} text
114+
$ sudo apt update
115+
```
116+
117+
Then:
118+
119+
```{code-block} text
120+
$ sudo apt upgrade
121+
```
122+
123+
Entering your password and pressing `Y` when prompted.
124+
125+
Next, install Node.js and npm:
126+
127+
```{code-block} text
128+
$ sudo apt-get install nodejs
129+
$ sudo apt install npm
130+
```
131+
132+
Press `Y` when prompted.
133+
134+
Now, create a new folder for our server.
135+
136+
```{code-block} text
137+
$ mkdir serverexample/
138+
```
139+
140+
Then navigate into it:
141+
142+
```{code-block} text
143+
$ cd serverexample/
144+
```
145+
146+
Now, open up your folder in Visual Studio Code, with the following command:
147+
148+
```{code-block} text
149+
$ code .
150+
```
151+
152+
The first time you do this, it will trigger a download for the necessary dependencies:
153+
154+
![Bash snippet showing the installation of Visual Studio Code Server's required dependencies.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/downloading-vscode-server.png?raw=true)
155+
156+
Once complete, your native version of Visual Studio Code will open the folder.
157+
158+
## Creating a basic web server
159+
160+
In Visual Studio Code, create a new `package.json` file and add the following text ([original example](https://learn.microsoft.com/en-gb/archive/blogs/cdndevs/visual-studio-code-and-local-web-server#3-add-a-packagejson-file-to-the-project-folder))
161+
162+
```{code-block} json
163+
{
164+
"name": "Demo",
165+
"version": "1.0.0",
166+
"description": "demo project.",
167+
"scripts": {
168+
"lite": "lite-server --port 10001",
169+
"start": "npm run lite"
170+
},
171+
"author": "",
172+
"license": "ISC",
173+
"devDependencies": {
174+
"lite-server": "^1.3.1"
175+
}
176+
}
177+
```
178+
179+
Save the file and then, in the same folder, create a new one called `index.html`
180+
181+
Add the following text, then save and close:
182+
183+
```{code-block} html
184+
<h1>Hello World</h1>
185+
```
186+
187+
Now return to your Ubuntu terminal (or use the Visual Studio Code terminal window) and type the following to install a server defined by the above specifications detailed in `package.json`:
188+
189+
```{code-block} text
190+
$ npm install
191+
```
192+
193+
Finally, type the following to launch the web server:
194+
195+
```{code-block} text
196+
$ npm start
197+
```
198+
199+
You can now navigate to `localhost:10001` in your native Windows web browser by using `CTRL+LeftClick` on the terminal links.
200+
201+
![Windows desktop showing a web server being run from a terminal with "npm start", A Visual Studio Code project with a "hello world" html file, and a web browser showing the "hello world" page being served on local host.](https://github.com/ubuntu/wsl/blob/main/docs/tutorials/assets/vscode/hello-world.png?raw=true)
202+
203+
That’s it!
204+
205+
By using Ubuntu on WSL you’re able to take advantage of the latest Node.js packages available on Linux as well as the more streamlined command line tools.
206+
207+
## Enjoy Ubuntu on WSL!
208+
209+
In this tutorial, we’ve shown you how to connect the Windows version of Visual Studio Code to your Ubuntu on WSL filesystem and launch a basic Node.js webserver.
210+
211+
We hope you enjoy using Ubuntu inside WSL. Don’t forget to check out our other tutorials for tips on how to optimise your WSL setup for Data Science.
212+
213+
### Further Reading
214+
215+
* [Install Ubuntu on WSL2](../howto/install-ubuntu-wsl2.md)
216+
* [Microsoft WSL Documentation](https://learn.microsoft.com/en-us/windows/wsl/)
217+
* [Setting up WSL for Data Science](https://ubuntu.com/blog/wsl-for-data-scientist)
218+
* [Ask Ubuntu](https://askubuntu.com/)

0 commit comments

Comments
 (0)