Skip to content

Commit 69e50a4

Browse files
ade555ade555
committed
[tutorial] modified WSL tutorial to include building with Python, running basic linux commands, interacting with WSL files from Windows explorer, using nano
1 parent 802605b commit 69e50a4

File tree

3 files changed

+171
-68
lines changed

3 files changed

+171
-68
lines changed

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

Lines changed: 171 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,19 @@ The easiest way to access your Ubuntu development environment in WSL is by using
44

55
## What you will learn
66

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
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
1111

1212
## What you will need
1313

14-
* A PC with Windows 10 or 11
14+
- A PC with Windows 10 or 11
1515

1616
## Install Ubuntu on WSL2
1717

18+
To begin installing Ubuntu on WSL2, the first step is to set up Windows Subsystem for Linux (WSL) on your machine. Once WSL is enabled, you'll install Ubuntu and verify the setup by running some basic Linux commands. This process will get you up and running with a fully functional Linux environment right on your Windows system.
19+
1820
### Install WSL
1921

2022
Open a PowerShell prompt as an Administrator and run:
@@ -32,7 +34,7 @@ WSL supports a variety of Ubuntu releases. Check our [reference on the distribut
3234
There are multiple ways of installing Ubuntu on WSL, here we focus on using the terminal.
3335
For other installation methods, refer to your dedicated guide:
3436

35-
* [Install Ubuntu on WSL2](https://documentation.ubuntu.com/wsl/en/latest/guides/install-ubuntu-wsl2/)
37+
- [Install Ubuntu on WSL2](https://documentation.ubuntu.com/wsl/en/latest/guides/install-ubuntu-wsl2/)
3638

3739
In a PowerShell terminal, run `wsl --list --online` to see all available distros and versions:
3840

@@ -51,9 +53,9 @@ Install using 'wsl --install -d <Distro>'.
5153
Ubuntu-24.04 Ubuntu 24.04 LTS
5254
...
5355
54-
```
56+
```
5557

56-
Your list may be different once new distributions become available.
58+
Your list may be different once new distributions become available.
5759

5860
You can install a version using a NAME from the output, for example:
5961

@@ -76,6 +78,79 @@ Use `wsl -l -v` to see all your currently installed distros and the version of W
7678
* Ubuntu-24.04 Stopped 2
7779
```
7880

81+
### Running basic Linux commands on WSL
82+
83+
After installation, you should run some basic commands to confirm your installation and get familiar with the Linux environment. You can run some of the commands listed below:
84+
85+
1. **pwd**: This will display the full path of your current location in WSL
86+
87+
2. **mkdir myFirstFolder**: This will create a directory (folder on windows) called **myFirstFolder**
88+
89+
## Creating and viewing files in your WSL development environment
90+
91+
WSL allows you to create files and folders from the terminal interface, just like Linux. Let's see how to create files in WSL and interact with the files in a native Windows app such as the file explorer.
92+
93+
### Create an HTML file in WSL
94+
95+
First, you should create a new directory (call it **ubuntuWSL** for this tutorial) to save your file. Use the `mkdir` command we saw earlier:
96+
97+
```{code-block} text
98+
$ mkdir ubuntuWSL
99+
```
100+
101+
Next, you should navigate into the new directory:
102+
103+
```{code-block} text
104+
$ cd ubuntuWSL
105+
```
106+
107+
After you complete the step above, you can create an HTML file by using `nano`. `nano` is a command-line text editor and it comes pre-installed with Ububtu WSL. You can use it to quickly create and edit files right from your terminal. Type this command to create a `index.html` file from the terminal:
108+
109+
```{code-block} text
110+
$ nano index.html
111+
```
112+
113+
The command above will open a text editor in your WSL instance. Paste this HTML snippet into the editor:
114+
115+
```html
116+
<!DOCTYPE html>
117+
<html lang="en">
118+
<head>
119+
<title>Document</title>
120+
</head>
121+
<body>
122+
<h1>Hello, World!</h1>
123+
</body>
124+
</html>
125+
```
126+
127+
Type `ctrl + s` to save your file and the `ctrl + x` to exit the edtior.
128+
To confirm that your file contains actual HTML, type `cat index.html`. You should see the content of your HTML file displayed on the terminal.
129+
130+
### Browse your WSL files in Windows explorer
131+
132+
Interacting with files and folders from the terminal can be daunting, especially for a Windows user. It is possible to interact with your files in WSL from Windows explorer by typing the command below:
133+
134+
```{code-block} text
135+
$ explorer.exe .
136+
```
137+
138+
The command will open up your current folder in Windows explorer.
139+
140+
### Serving static HTML in WSL with Python
141+
142+
Python is a programming language that comes pre-installed with Ubuntu in WSL. You can use it for multiple things, including serving HTML files to your browser. In your command like, type ths following command:
143+
144+
```{code-block} python
145+
$ python3 -m http.server
146+
```
147+
148+
Next, visit `http://localhost:8000/` to see your HTML document displayed on the browser:
149+
150+
![HTML web page displaying "hello world" in bold text](media/html-web-page-displaying-hello-world-in-bold-text.png)
151+
152+
You can exit the server by typing `ctrl +c`
153+
79154
## Install Visual Studio Code on Windows
80155

81156
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.
@@ -86,11 +161,11 @@ Then click **Install**.
86161

87162
![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)
88163

89-
Alternatively, you can install Visual Studio Code from the web link [here](https://code.visualstudio.com/Download).
164+
Alternatively, you can install Visual Studio Code [from the web link](https://code.visualstudio.com/Download).
90165

91166
![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)
92167

93-
During installation, under the 'Additional Tasks' step, ensure the `Add to PATH` option is checked.
168+
During installation, under the 'Additional Tasks' step, ensure you check the `Add to PATH` option.
94169

95170
![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)
96171

@@ -100,109 +175,137 @@ Once the installation is complete, open Visual Studio Code.
100175

101176
Navigate to the `Extensions` menu in the sidebar and search for `Remote Development`.
102177

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`.
178+
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` via the terminal.
104179

105180
![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)
106181

107-
Once installed we can test it out by creating an example local web server with Node.js
182+
Once installed we can test it out by creating an example local web server with Python.
183+
184+
## Create a new Python project
108185

109-
## Install Node.js and create a new project
186+
Python is a programming languages that comes pre-installed with WSL so you don't need to install it like you would on native Windows. We'll build a simple web server with Python to demonstrate how to work with WSL from windows.
110187

111-
Open your WSL Ubuntu terminal and ensure everything is up to date by typing:
188+
Open your WSL Ubuntu terminal and create a new folder for our server:
112189

113190
```{code-block} text
114-
$ sudo apt update
191+
$ mkdir serverexample/
115192
```
116193

117-
Then:
194+
Then navigate into it:
118195

119196
```{code-block} text
120-
$ sudo apt upgrade
197+
$ cd serverexample/
121198
```
122199

123-
Entering your password and pressing `Y` when prompted.
124-
125-
Next, install Node.js and npm:
200+
Now, open up your folder in Visual Studio Code, with the following command:
126201

127202
```{code-block} text
128-
$ sudo apt-get install nodejs
129-
$ sudo apt install npm
203+
$ code .
130204
```
131205

132-
Press `Y` when prompted.
206+
The first time you do this, it will trigger a download for the necessary dependencies:
207+
208+
![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)
209+
210+
Once complete, your native version of Visual Studio Code will open the folder.
211+
212+
### Creating a virtual environment and installing dependencies
133213

134-
Now, create a new folder for our server.
214+
In Visual Studio Code, type `ctrl + j` to open up a terminal with a WSL instance. We'll create our virtual environment and install necessary packages here.
215+
216+
Inside your terminal type this command:
135217

136218
```{code-block} text
137-
$ mkdir serverexample/
219+
$ python3 -m venv env
138220
```
139221

140-
Then navigate into it:
222+
Now, activate the virtual environment with this command:
141223

142224
```{code-block} text
143-
$ cd serverexample/
225+
source env/bin/activate
144226
```
145227

146-
Now, open up your folder in Visual Studio Code, with the following command:
228+
After you type the command, you will notice that `(env)` appears before your prompt. This means your virtual environment is active.
229+
230+
Now, you can install the necessary dependencies for the project. In this tutorial, we'll only use Flask. Type this command in your terminal:
147231

148232
```{code-block} text
149-
$ code .
233+
$ pip install flask
150234
```
151235

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)
236+
If you face issues, try using `pip3` instead of `pip`.
155237

156-
Once complete, your native version of Visual Studio Code will open the folder.
238+
Once Flask is installed, we can build our basic web server with it.
157239

158240
## Creating a basic web server
159241

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))
242+
We'll create a basic web server that takes the user's name as input and returns a greeting message.
161243

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-
```
244+
In Visual Studio Code, create a file called `app.py` and paste this code into it:
178245

179-
Save the file and then, in the same folder, create a new one called `index.html`
246+
```{code-block} python
247+
from flask import Flask, request, render_template
180248
181-
Add the following text, then save and close:
249+
app = Flask(__name__)
182250
183-
```{code-block} html
184-
<h1>Hello World</h1>
251+
@app.route("/", methods=["GET", "POST"])
252+
def home():
253+
name = None
254+
if request.method == "POST":
255+
name = request.form.get("name")
256+
return render_template("index.html", name=name)
257+
258+
if __name__ == "__main__":
259+
app.run(debug=True)
185260
```
186261

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`:
262+
The code above defines a single route that listens for a POST request and returns an HTML template.
263+
Save the file and close it.
188264

189-
```{code-block} text
190-
$ npm install
265+
Now create a folder called `templates`. Inside it, create a file called `index.html`. You should paste the code below into the file:
266+
267+
```{code-block} html
268+
<!DOCTYPE html>
269+
<html>
270+
<head>
271+
<title>Greeting App</title>
272+
<style>
273+
body {
274+
display: flex;
275+
justify-content: center;
276+
align-items: center;
277+
height: 100vh;
278+
}
279+
</style>
280+
</head>
281+
<body>
282+
<div>
283+
<h2>Enter your name:</h2>
284+
<form method="post">
285+
<input type="text" name="name" required />
286+
<button type="submit">Submit</button>
287+
</form>
288+
{% if name %}
289+
<h3>Hello, {{ name }}!</h3>
290+
{% endif %}
291+
</div>
292+
</body>
293+
</html>
191294
```
192295

193-
Finally, type the following to launch the web server:
296+
The HTML above simply contains a form to take user input and displays a greeting with their name if they enter it.
297+
298+
Now save your files and type this command in your terminal:
194299

195300
```{code-block} text
196-
$ npm start
301+
$ python3 app.py
197302
```
198303

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)
304+
Next, navigate to `http://127.0.0.1:5000/` in your browser. You should see the image below. Type in your name and confirm that it returns a greeting.
202305

203-
That’s it!
306+
![HTML web page in a browser that displays a form with a submit button, and single input, asking for the user's name.](media/html-webpage-that-displays-a-form-asking-for-the-users-name.png)
204307

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.
308+
That's it! You have successfully created a web server inside WSL and displayed it in a Wiindows native browser.
206309

207310
## Enjoy Ubuntu on WSL!
208311

@@ -212,7 +315,7 @@ We hope you enjoy using Ubuntu inside WSL. Don’t forget to check out our other
212315

213316
### Further Reading
214317

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/)
318+
- [Install Ubuntu on WSL2](../howto/install-ubuntu-wsl2.md)
319+
- [Microsoft WSL Documentation](https://learn.microsoft.com/en-us/windows/wsl/)
320+
- [Setting up WSL for Data Science](https://ubuntu.com/blog/wsl-for-data-scientist)
321+
- [Ask Ubuntu](https://askubuntu.com/)

‎wsl/tutorial/media/html-web-page-displaying-hello-world-in-bold-text.png‎

34.6 KB
Loading

‎wsl/tutorial/media/html-webpage-that-displays-a-form-asking-for-the-users-name.png‎

35.5 KB
Loading

0 commit comments

Comments
 (0)