mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
docs(NA): windows wsl development (#134589)
* docs(NA): windows wsl development * docs(NA): update titles for the documentation created * chore(NA): update dev_docs/tutorials/development_windows.mdx Co-authored-by: Jonathan Budzenski <jon@budzenski.me> * docs(NA): updated guide to include info around GUI apps support * docs(NA): updated guide to include info around GUI apps support * docs(NA): include win10 GUI workaround * docs(NA): run a first sudo command before running others * docs(NA): added remote code wsl extension * docs(NA): mentioned NVIDIA does now includes vGPU drivers for WSL within the common drivers * docs(NA): update sudo commands separation * docs(NA): added hardware virtualization prerequisite awareness into the guide * docs(NA): update wording on guide recomendation for win11 Co-authored-by: Jonathan Budzenski <jon@budzenski.me> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Tiago Costa
GitHub
parent
cdcb272082
commit
1599cd8d2a
4 changed files with 171 additions and 48 deletions
|
|
@ -1,45 +0,0 @@
|
|||
---
|
||||
id: kibDevTutorialSetupDevWindows
|
||||
slug: /kibana-dev-docs/tutorial/setup-dev-windows
|
||||
title: Development on Windows
|
||||
summary: Learn how to setup a development environment on Windows
|
||||
date: 2021-08-11
|
||||
tags: ['kibana', 'onboarding', 'dev', 'windows', 'setup']
|
||||
---
|
||||
|
||||
|
||||
# Overview
|
||||
|
||||
Development on Windows is recommended through WSL2. WSL lets users run a Linux environment on Windows, providing a supported development environment for Kibana.
|
||||
|
||||
## Install WSL
|
||||
|
||||
The latest setup instructions can be found at https://docs.microsoft.com/en-us/windows/wsl/install-win10
|
||||
|
||||
1) Open Powershell as an administrator
|
||||
1) Enable WSL
|
||||
```
|
||||
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
|
||||
```
|
||||
1) Enable Virtual Machine Platform
|
||||
```
|
||||
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
|
||||
```
|
||||
1) Download and install the [Linux kernel update package](https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi)
|
||||
1) Set WSL 2 as the default version
|
||||
```
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
1) Open the Micrsoft Store application and install a Linux distribution
|
||||
|
||||
## Setup Kibana
|
||||
|
||||
1. <DocLink id="kibDevTutorialSetupDevEnv" text="Set up your development environment" />
|
||||
|
||||
## Install VS Code
|
||||
|
||||
Remote development is supported with an extension. [Reference](https://code.visualstudio.com/docs/remote/wsl).
|
||||
|
||||
1) Install VS Code on Windows
|
||||
1) Check the "Add to PATH" option during setup
|
||||
1) Install the [Remote Development](https://aka.ms/vscode-remote/download/extension) package
|
||||
|
|
@ -13,9 +13,11 @@ Setting up a development environment is pretty easy.
|
|||
In order to support Windows development we currently require you to use one of the following:
|
||||
|
||||
- [Git Bash](https://git-scm.com/download/win)
|
||||
- [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
|
||||
- [Windows Subsystem for Linux (recommended)](https://docs.microsoft.com/en-us/windows/wsl/about)
|
||||
|
||||
Before running the steps below, please make sure you have installed [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145) and that you are running all commands in either Git Bash or WSL.
|
||||
If you want to know more about how to setup and use WSL for development on Windows, which will become our only supported way in the upcoming future, please check our <DocLink id="kibDevTutorialSetupWindowsDevWSL" text="tutorial"/>.
|
||||
|
||||
Before running the steps below, please make sure you have installed [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145) and that you are running all commands in either Git Bash or WSL.
|
||||
|
||||
</DocCallOut>
|
||||
|
||||
|
|
|
|||
163
dev_docs/tutorials/development_windows.mdx
Normal file
163
dev_docs/tutorials/development_windows.mdx
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
---
|
||||
id: kibDevTutorialSetupWindowsDevWSL
|
||||
slug: /kibana-dev-docs/tutorial/setup-windows-development-wsl
|
||||
title: WSL on Windows Development
|
||||
summary: Learn how to setup a Windows development environment using WSL
|
||||
date: 2022-06-16
|
||||
tags: ['kibana', 'onboarding', 'setup', 'windows', 'development', 'wsl']
|
||||
---
|
||||
|
||||
|
||||
# Overview
|
||||
|
||||
Development on Windows is recommended through WSL2. WSL lets users run a Linux environment on Windows, providing a supported development environment for Kibana.
|
||||
|
||||
<DocCallOut title="Prerequisites">
|
||||
|
||||
This guide allows you to achieve two different kind of experiences (Basic and Default each with their specifics). While we fully advise for upgrading into Windows 11 to use the much better Default experience (and will eventually remove the basic one from this guide),
|
||||
for now both have a common prerequisite on enabling the hardware virtualization.
|
||||
|
||||
Get that feature to work will highly depend on your hardware, as it should be enabled on your UEFI (or BIOS). Please check the official Microsoft documentation on
|
||||
[How to Enable Virtualization on Windows](https://support.microsoft.com/en-us/windows/enable-virtualization-on-windows-11-pcs-c5578302-6e43-4b4b-a449-8ced115f58e1).
|
||||
|
||||
After successfully achieve the previous step there is a second good guide describing [How to Enable Hyper-V Platform Feature on Windows](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v#enable-the-hyper-v-role-through-settings).
|
||||
|
||||
Once hardware virtualization is enabled on Windows, please pay attention to the specific prerequisites for each type of experience listed below.
|
||||
|
||||
### Basic Experience
|
||||
For a basic WSL usage you must be running **Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11**. Note that in a basic setup you won't be able to use
|
||||
the browser GUI to visually run and/or debug functional tests. It's highly advisable to make sure you install the prerequisites for a default usage listed below.
|
||||
|
||||
**Note:** For a normal development cycle we really advise to use the default experience setup within Windows 11. However if you have an explicit need for using a browser GUI
|
||||
while using Windows 10, please follow each step of the guide below applicable for the Basic Experience setup and then check our <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="short-term-workaround-for-windows-10-gui-support" text="short term workaround for Windows 10 GUI support" />.
|
||||
|
||||
### Default Experience
|
||||
For a default experience and a completion of the entire guide which will make you able to run GUI apps you must be running **Windows 11 (Build 22000 and higher)**.
|
||||
In addition to that, installing a **vGPU driver** is also required. Please choose the one compatible with your hardware:
|
||||
|
||||
- [Intel GPU driver for WSL](https://www.intel.com/content/www/us/en/download/19344/intel-graphics-windows-dch-drivers.html?)
|
||||
- [AMD GPU driver for WSL](https://www.amd.com/en/support/kb/release-notes/rn-rad-win-wsl-support)
|
||||
- [NVIDIA GPU driver for WSL](https://developer.nvidia.com/cuda/wsl) (**Note:** NVIDIA does now includes the vGPU driver in their common gpu drivers. Please make sure you have your latest available drivers installed or refer to the previous link for official documentation)
|
||||
|
||||
More information for that could be found in the [official guide for GUI apps on WSL](https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-support-for-linux-gui-apps).
|
||||
</DocCallOut>
|
||||
|
||||
## Install WSL
|
||||
|
||||
The latest setup instructions can be found at https://docs.microsoft.com/en-us/windows/wsl/install
|
||||
|
||||
1. Open Powershell as an administrator
|
||||
|
||||
2. Install WSL with Ubuntu and restart the machine when prompted
|
||||
```
|
||||
wsl --install -d Ubuntu
|
||||
```
|
||||
|
||||
In case you already have WSL installed you can just `wsl --update` and then reboot the machine.
|
||||
|
||||
3. Once rebooted the installation will proceed for a new WSL install. If that's not the case make sure you're using
|
||||
WSL2 and Ubuntu by
|
||||
```
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```
|
||||
wsl --set-default Ubuntu
|
||||
```
|
||||
|
||||
4. Install support for Google Chrome by running the following inside WSL shell **(IMPORTANT: <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="default-experience" text="Default Experience Only"/>)**
|
||||
|
||||
Start by updating your apt package sources list with
|
||||
```
|
||||
sudo apt update
|
||||
```
|
||||
|
||||
Enter your user password, then
|
||||
```
|
||||
sudo apt -y upgrade && sudo apt -y autoremove
|
||||
cd /tmp
|
||||
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
|
||||
sudo dpkg -i google-chrome-stable_current_amd64.deb
|
||||
sudo apt install --fix-broken -y
|
||||
sudo dpkg -i google-chrome-stable_current_amd64.deb
|
||||
```
|
||||
|
||||
Now you can launch Google Chrome by either `google-chrome` on your WSL shell or from Ubuntu Applications on Windows.
|
||||
|
||||
It's also worth it to check if there are other useful [GUI packages you would want to add on WSL](https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#update-the-packages-in-your-distribution) and then the configuration is complete.
|
||||
|
||||
## Setup Kibana
|
||||
|
||||
The next step is now <DocLink id="kibDevTutorialSetupDevEnv" section="get-the-code" text="setup your development environment" /> for Kibana inside WSL just like in any other case.
|
||||
|
||||
## Install VSCode
|
||||
|
||||
Even though in previous steps you might have installed Nautilus and other X11 apps that allows you to use the file explorer for the WSL environment or even using some apps supported by X11 like
|
||||
Sublime Text our recommended way to write your code is by using VSCode installed natively on Windows and then use its remote development extension to connect into the WSL environment. You can do this
|
||||
by completing the following:
|
||||
|
||||
1. Install VSCode on Windows
|
||||
2. Check the "Add to PATH" option during setup
|
||||
3. Install the [Remote Development](https://code.visualstudio.com/docs/remote/wsl) package
|
||||
|
||||
For more information you can find the official documentation on how to Remote development is supported with an extension [here](https://code.visualstudio.com/docs/remote/wsl).
|
||||
|
||||
## Success
|
||||
|
||||
At this point you should be able to develop Kibana using WSL by writing code on VSCode, running commands for build, test and manage your dev environment using the WSL shell and finally having a basic GUI
|
||||
support for your WSL environment using the applications we recommended like Google Chrome and others you choose to install like for example Nautilus file manager or other X11 based ones.
|
||||
|
||||
## Short Term Workaround for Windows 10 GUI Support
|
||||
|
||||
As mentioned before is highly recommended you setup your environment for a default experience using Windows 11. If you're reading this section is because you are not available to do that for a reason and
|
||||
at the same time you still have the need for a GUI browser on Windows 10. Next you can find our recommendations for a short term workaround to achieve that for Windows 10 before we could terminate the support
|
||||
for this operating system.
|
||||
|
||||
1. Fulfil the <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="basic-experience" text="prerequisites for basic experience"/> as well as installing the <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="default-experience" text="vGPU drivers from the default experience"/>.
|
||||
|
||||
2. Make sure you've followed <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="install-wsl" text="Install WSL"/> up to step 3, <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="setup-kibana" text="Setup Kibana"/> and <DocLink id="kibDevTutorialSetupWindowsDevWSL" section="install-vscode" text="Install VSCode"/>.
|
||||
|
||||
3. Install Google Chrome and it's dependencies by
|
||||
```
|
||||
cd /tmp
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y curl unzip xvfb libxi6 libgconf-2-4
|
||||
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
|
||||
sudo apt install ./google-chrome-stable_current_amd64.deb
|
||||
```
|
||||
|
||||
Then run `google-chrome --version` and you should be able to get the current version installed printed out.
|
||||
|
||||
4. Download [VcXsrv](https://sourceforge.net/projects/vcxsrv) and install it natively on your **Windows**. Once installed go to the program files folder for VcXsrv and run `xlaunch.exe`. The majority of the default
|
||||
settings are okay but make sure `Disable access control` is checked. In doubt, check the same settings as shown into this [Github issue image](https://github.com/microsoft/WSL/issues/4106#issuecomment-502920377).
|
||||
Next, allow this application through the firewall if prompted when its first ran. Otherwise, if not asked, please go to `Windows firewall -> Allow an app through firewall -> click change settings -> select BOTH entries of "VcXsrv windows server" -> OK`.
|
||||
|
||||
5. Configure the `DISPLAY` env var which in Linux tells GUI applications at which IP address the X Server is running. On WSL2 the IP for the native Windows is not localhost, so we need
|
||||
to set DISPLAY to the correct IP address. Let's go ahead and add the following into the `.bashrc` file of your WSL environment:
|
||||
```
|
||||
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0
|
||||
```
|
||||
Once complete, running `echo $DISPLAY` inside your WSL shell should print the Windows native IP suffixed by `:0.0`.
|
||||
|
||||
6. When reaching that point, if you run `google-chrome` on the WSL shell, the Chrome browser should open inside an X server window on Windows which should also work as expected when the functional tests chromedriver will try to use a browser to run into.
|
||||
|
||||
### Troubleshooting the workaround
|
||||
|
||||
#### Unable to open X display
|
||||
|
||||
If that is seen when running the Google Chrome
|
||||
|
||||
```
|
||||
Error: /etc/machine-id contains 0 characters (32 were expected).
|
||||
Unable to open X display
|
||||
```
|
||||
|
||||
- Make sure VcXsrv is running in Windows with “Disable access control” checked.
|
||||
- Make sure VcXsrv is whitelisted in the Windows firewall (search the start menu for “Allow a program through Windows firewall” and enable it there)
|
||||
|
||||
### More information
|
||||
|
||||
For more information on how to configure this alternative X server or to troubleshoot other problems please check
|
||||
the [official documentation](https://sourceforge.net/p/vcxsrv/wiki/VcXsrv%20%26%20Win10/) or a [popular Github issue](https://github.com/microsoft/WSL/issues/4106#issuecomment-502920377).
|
||||
|
|
@ -100,6 +100,9 @@
|
|||
{
|
||||
"label": "Tutorials",
|
||||
"items": [
|
||||
{
|
||||
"id": "kibDevTutorialSetupWindowsDevWSL"
|
||||
},
|
||||
{
|
||||
"id": "kibDevTutorialTestingPlugins"
|
||||
},
|
||||
|
|
@ -519,4 +522,4 @@
|
|||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue