From 0644bc004dd1186426bb8c945003393183ad6909 Mon Sep 17 00:00:00 2001 From: 360dgries <139473729+360dgries@users.noreply.github.com> Date: Tue, 24 Oct 2023 14:40:16 -0400 Subject: [PATCH] Added Documentation for Windows (#375) * Added Documentation for Windows * Added information about WSL networking issues --------- Co-authored-by: Rob Scanlon --- README.md | 4 ++++ docs/Gemfile.lock | 3 +++ docs/getting-started.md | 26 ++++++++++++++++++++++++-- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 22b397f24..f98db40da 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,10 @@ or GET http://localhost:4567/inferno/api/test_sessions/TEST_SESSION_ID/results ``` +## Running on Windows +Inferno Core requires a WSL instance in order to run. Instructions for setting +that up can be found at the [Inferno Framework documentation](https://inferno-framework.github.io/inferno-core/getting-started.html#development-with-ruby) + ## Development in a Ruby console To get to an interactive console, run `bundle exec bin/inferno console` diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 5295c70ee..147309c2c 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -219,6 +219,8 @@ GEM racc (~> 1.4) nokogiri (1.14.3-x86_64-darwin) racc (~> 1.4) + nokogiri (1.14.3-x86_64-linux) + racc (~> 1.4) octokit (4.25.1) faraday (>= 1, < 3) sawyer (~> 0.9) @@ -262,6 +264,7 @@ GEM PLATFORMS arm64-darwin-21 x86_64-darwin-20 + x86_64-linux DEPENDENCIES github-pages (~> 227) diff --git a/docs/getting-started.md b/docs/getting-started.md index 19df99963..d6b9ee124 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -113,12 +113,34 @@ Put the `package.tgz` for the IG you're writing tests for in to the resources needed to validate resources against your IG. ### Development with Ruby - +___ +**NOTE:** Windows developers will need to use [WSL](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-wsl-2) in order to interact with Inferno. It is recommended that you also follow [the steps for installing node.js](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl#install-nvm-nodejs-and-npm). Once you have WSL (and node.js) set up: +{: .fs-3} + +1. Install VS Code and the [WSL Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl). +1. Install [Ubuntu from the Windows Store](https://www.microsoft.com/store/productId/9PDXGNCFSCZV). +1. Open Command Prompt and run `ubuntu`. + 1. You will have to setup a user and password for this linux subsytem. + 2. The password will be used for `sudo` commands later, so remember these credentials! +1. Install Docker Desktop for Windows. + 1. Follow the steps from Docker to ensure it plays nicely with WSL, see [here](https://docs.docker.com/desktop/wsl/#turn-on-docker-desktop-wsl-2). + 2. From the Docker settings, Open Resources > WSL Integration, and make sure Ubuntu is selected. Then, hit "Apply and Restart". +1. From VS Code, press Ctrl + Shift + P to open the command palette, and type "WSL". Select "Connect to WSL in new Window using distro..." and select Ubuntu. +1. Open a terminal in the new WSL window and try to `ping google.com`. + 1. If you cannot ping google.com, you may not be able to connect to the internet from within the WSL instance. The steps at [this stack overflow article](https://stackoverflow.com/questions/55649015/could-not-resolve-host-github-com-only-in-windows-bash#:~:text=It%20could%20be%20that%20your%20/etc/resolv.conf%20file%20is%20corrupt%20%2D%20it%20happened%20to%20me!) should resolve the issue. If it does not, open cmd and run `nslookup`. Copy the Default Address, then in your wsl instance type `sudo nano /etc/resolv.conf`. Add the default address as another nameserver. +1. Continue from step 2 in [Installation](#installation). +{: .lh-default} + +**NOTE:** If, when running Inferno within WSL, the tests begin to stall and the console repeatedly prints `WARN: Your Redis network connection is performing extremely poorly.`, +WSL may be having networking issues. To resolve this, you can follow the steps in this [WSL Slow Network Issue thread](https://github.com/microsoft/WSL/issues/4901#issuecomment-1724482084). You can make a `.wslconfig` file from your `%USERDATA%` directory if it does not already exist, and you will need to restart WSL (usually through `wsl --shutdown` in Windows Powershell) before the changes take effect. +{: .fs-3} + +___ #### Installation 1. Install [Docker](https://www.docker.com/get-started). 1. Install Ruby. It is highly recommended that you install ruby via a [ruby version - manager](https://www.ruby-lang.org/en/documentation/installation/#managers). + manager](https://www.ruby-lang.org/en/documentation/installation/#managers). Use the manager's documentation for instructions on installing/switching ruby versions, and be sure to download the same ruby version that is in `.ruby-version` in the repo. 1. Install [Docker](https://www.docker.com/get-started). 1. Clone the [Inferno Template repository](https://github.com/inferno-framework/inferno-template). You can