├── .canvas ├── .learn └── README.md /.canvas: -------------------------------------------------------------------------------- 1 | --- 2 | :lessons: 3 | - :page_id: 3896 4 | :course_id: 154 5 | :canvas_url: https://learning.flatironschool.com/courses/154/pages/wsl-setup-2 6 | :type: page 7 | -------------------------------------------------------------------------------- /.learn: -------------------------------------------------------------------------------- 1 | languages: 2 | - n/a 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Setting up Windows Subsystem for Linux for Development 2 | 3 | *You must be running Windows 10 to perform this procedure.* If you are using a different operating system, check [When should I set up a local environment](https://help.learn.co/en/articles/1394611-when-should-i-set-up-a-local-environment) to find out what setup instructions you should follow. 4 | 5 | *Note: It is no longer necessary to enable developer mode for Windows Subsystem Linux to work.* 6 | 7 | ## Getting Windows Ready 8 | 9 | 1) Windows Subsystem Linux (WSL) is **not** automatically enabled on windows. So, to start off, we need to enable it! 10 | 11 | a. Go to your Windows Search bar and type in `turn windows features on or off` 12 | 13 | b. Click on the result that matches your query. It will be in your Control Panel. You should see something like this: 14 | 15 | ![toggle windows features](https://curriculum-content.s3.amazonaws.com/setup-instructions/turn-windows-features-on-or-off.png) 16 | 17 | c. Scroll down until you see "Windows Subsystem for Linux" - ensure its box 18 | is checked! 19 | 20 | ![wsl checkbox](https://curriculum-content.s3.amazonaws.com/setup-instructions/wsl-turnon.png) 21 | 22 | d. Scroll up a bit until you see "Virtual Machine Platform." Turn this 23 | feature on as well. 24 | 25 | ![virtual machine platform checkbox](https://curriculum-content.s3.amazonaws.com/setup-instructions/wsl-virtual-machine-platform.png) 26 | 27 | > **Note:** The "Virtual Machine Platform" was added in a February 2020 28 | > update to Windows. If your computer has not received this update, this 29 | > feature may not be available. In this case, just make sure "Windows 30 | > Subsystem for Linux" is enabled and continue on. Keep in mind that if you 31 | > update, you may need to go back and enable this feature. 32 | 33 | 2) **Restart your computer** 34 | 35 | 3) Check your Windows 10 version by going to `System Information` and checking your Version. If your build is earlier than 16215, skip step 4 and proceed to step 5. 36 | 37 | ![windows version](https://curriculum-content.s3.amazonaws.com/setup-instructions/windows-version.png) 38 | 39 | 4) Open up Microsoft Store. Search for "Ubuntu" 40 | 1) Choose "Ubuntu" (not 16.04 LTS or 18.04 LTS) 41 | 42 | 43 | ![ubuntu choice in microsoft store](https://curriculum-content.s3.amazonaws.com/setup-instructions/ubuntu-choice.png) 44 | 45 | 5) If you run into errors or if you have an early version of Windows 10, see further information [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10) 46 | 47 | 6) Open up the Ubuntu app. Follow the prompts, which will include making a username and password. Don't forget your password! 48 | 49 | ![open ubuntu](https://curriculum-content.s3.amazonaws.com/setup-instructions/open-ubuntu.png) 50 | 51 | 52 | Note: if you get an error at this step, see FAQ below. 53 | 54 | ## Start Outfitting your new Linux Subsystem: RVM / Ruby, learn-co, git, NodeJS, and Rails 55 | 56 | 7) Once everything is set up, we can start setting up our system! Start off by running the following to download our dependencies: 57 | 58 | 59 | ``` 60 | sudo apt-get update 61 | ``` 62 | 63 | ``` 64 | sudo apt-get install git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev libpq-dev libgdbm-dev libncurses5-dev automake libtool bison gnupg postgresql postgresql-contrib 65 | ``` 66 | 67 | 8) Install RVM by running: 68 | 69 | ``` 70 | gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB 71 | ``` 72 | 73 | > __Note:__ There are two possible errors you may see at this point. Follow the appropriate instructions below: 74 | 75 | > **(A) If** the previous command does not work the first time (with the error `keyserver receive failed: No dirmngr` and/or `IPC connect call failed`, try running it again. 76 | > If the second time works, you should see public keys imported by Piotr Kuczynski and Michal Papis. You can now continue with the procedure and disregard the rest of the instructions in this shaded area. 77 | > If the command still does not work (you still get the same errors as the first attempt), then perform the following: 78 | > 79 | > ``` 80 | > sudo apt-get install gnupg2 -y 81 | > gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB 82 | > ``` 83 | > 84 | > **(B) If** the original error you get is `[gpg] keyserver receive failed: Server indicated a failure`, run the following command (following the instructions above if you get the error above): 85 | > ``` 86 | > gpg --keyserver hkp://keys.gnupg.net:80 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB 87 | > ``` 88 | 89 | Once you have successfully run either the `gpg` or the `gpg2` command above. Check if `curl` is installed: 90 | 91 | ``` 92 | curl -V 93 | ``` 94 | 95 | If not, install it: 96 | 97 | ``` 98 | sudo apt-get install curl 99 | ``` 100 | 101 | Then run the following: 102 | 103 | ``` 104 | \curl -sSL https://get.rvm.io | bash -s stable --ruby 105 | ``` 106 | 107 | When RVM finishes installing, close out of Ubuntu entirely and reopen it to make sure RVM is running. 108 | 109 | 9) Next, to set up a ruby version most compatible with Learn.co labs, we want to download ruby 2.7.3 and set it as our default: 110 | 111 | ``` 112 | rvm install 2.7.3 113 | rvm use 2.7.3 --default 114 | ``` 115 | 116 | 10) Let's install the bundler gem: 117 | 118 | ``` 119 | gem install bundler 120 | ``` 121 | 122 | 11) And set up git: 123 | 124 | ``` 125 | git config --global color.ui true 126 | ``` 127 | 128 | For the next few commands, make sure to input your specific information: 129 | 130 | ``` 131 | git config --global user.name "your_name" 132 | ``` 133 | 134 | ``` 135 | git config --global user.email "your_email@example.com" 136 | ``` 137 | 138 | You can either communicate with your remote repositories via HTTPS or SSH. If you want to use SSH (which means you will not have to authenticate with your GitHub username and password before each push) - [follow these instructions.](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) 139 | 140 | 12) Now we can get set up with the learn-co gem. This will allow you to use commands like `learn`, `learn submit`, and `learn open`. 141 | 142 | ``` 143 | gem install learn-co 144 | ``` 145 | 146 | - In your browser: 147 | - If you have connected your Github account to your Learn account, navigate to learn.co/your_github_username 148 | - If you have not connected your Github account: Go to [your profile](https://learn.co/account/profile) > Learn Settings > Public Profile. Click on the link under **Username** 149 | - At the bottom of the page, you should see text that says `OAuth Token:` followed by a token. Copy the token, and then go back to your WSL terminal 150 | - Type: 151 | 152 | ``` 153 | learn whoami 154 | ``` 155 | 156 | - Paste in your token 157 | 158 | You should now be fully authenticated with learn. 159 | 160 | 13) Now let's get Node Version Manager, NodeJS, and Rails installed so we can make a bunch of stuff! 161 | 162 | - First, install NVM: 163 | 164 | ``` 165 | curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash 166 | ``` 167 | 168 | - Then, reload bash profile into current session: 169 | 170 | ``` 171 | source ~/.bashrc 172 | ``` 173 | 174 | - Next, install NodeJS: 175 | 176 | ``` 177 | nvm install node 178 | ``` 179 | 180 | - Now, Ruby on Rails: 181 | 182 | ``` 183 | gem install rails 184 | ``` 185 | 186 | ## Choose your programming editor: VSCode 187 | 188 | You can use any editor you want, but I am going to be walking through setting up VSCode. 189 | 190 | 14) Download VSCode [here](https://code.visualstudio.com/download). Choose the Windows download, not the Linux download. Any required Linux downloads will be done via the Ubuntu terminal, and everything else should be downloaded for your Windows OS. 191 | 192 | 15) To configure your Ubuntu terminal to be available in VSCode: 193 | 194 | - open up VSCode 195 | - open the Command Palette via `F1` or `Ctrl`+`Shift`+`p` 196 | - begin typing the following: `Terminal: Select Default Profile` until you see it. Select that option. 197 | 198 | ![command palette](https://curriculum-content.s3.amazonaws.com/setup-instructions/default-shell.png) 199 | 200 | - Once you select it, a few options will pop up. You want to select WSL 201 | 202 | ![WSL Terminal](https://curriculum-content.s3.amazonaws.com/setup-instructions/wsl-bash-selection.png) 203 | 204 | 16) Now, you can use your Ubuntu terminal in VSCode. Select "New Terminal" in the "Terminal" drop-down, or type `Ctrl`+`Shift`+` in order to use it! 205 | 206 | 17) Additional User Settings *(OPTIONAL)*: 207 | - You can add a few things to your User Settings to customize and improve your programming experience. Most importantly, we can make VSCode treat .erb files like .html files, allowing us to use all the same shortcuts and get the same syntax highlighting. 208 | - To open up user settings, again open up the Command Palette using `F1` or `Ctr`+`Shift`+`p` and type `Preferences: Open Settings (JSON)` 209 | 210 | ![Preferences - settings](https://curriculum-content.s3.amazonaws.com/setup-instructions/settings-json.png) 211 | 212 | - You will see a screen like this: 213 | 214 | ![Preferences - settings](https://curriculum-content.s3.amazonaws.com/setup-instructions/user-settings.png) 215 | 216 | - To have your erb files treated like html, add the following to your user settings (circled above): 217 | 218 | ``` 219 | "emmet.includeLanguages": { 220 | "erb": "html" 221 | } 222 | ``` 223 | 224 | - Some optional personal preferences that I like: 225 | 226 | ``` 227 | "window.zoomLevel": -1, 228 | "editor.acceptSuggestionOnEnter": "off", 229 | "editor.fontSize": 11, 230 | "editor.fontFamily": "Hack, Consolas, 'Courier New', monospace", 231 | ``` 232 | 233 | - Note that for the Hack font to be usable, you have to download it. You can check it out [here](https://sourcefoundry.org/hack/). 234 | 235 | 18) Update your .learn-config 236 | - Travel to your Linux home directory by typing `cd`, you can change your .learn-config by typing: 237 | 238 | ``` 239 | nano .learn-config 240 | ``` 241 | 242 | - and customizing where you want the ```learn open``` command to save labs, and setting your editor to VSCode. Here's what it should look like: 243 | 244 | ``` 245 | --- 246 | :learn_directory: "/mnt/c/users//dev/flatiron/labs" 247 | :editor: code 248 | ``` 249 | 250 | - You save a file you have modified in `nano` by following the directions at the bottom of the screen: click `Ctrl`+`X` and then `y` and then `Enter` to save your changes. 251 | 252 | - If you feel uncomfortable with these commands, check out the basic Linux commands link below in the resources. 253 | 254 | ## Important Knowledge: Basic Use 255 | 256 | Your terminal is actually accessing an Ubuntu Virtual Machine which is running inside of your Windows OS. If you ever ```cd``` in your terminal, you will be sent to the 'user home' of your Linux VM. That is also the default location you will be in when you open your Ubuntu app. You actually want to do all of your business inside of your normal Windows file space, not your Linux VM file space. So, you will need to know how to navigate in your terminal from your Ubuntu file system to your Windows file system. This is pretty simple if you understand how the system is set up, so let's go over that quickly. 257 | 258 | To allow you to access the functionality of a Linux machine, Windows stores the Ubuntu OS and file system inside of its own file system. You should NEVER access your Ubuntu files via your Windows machine. What you SHOULD do is save everything you are working on in your normal Windows filespace, and access that via your Ubuntu terminal. So, how do you do that? Well, from the Ubuntu's point of view, it is just a normal Linux machine, but Microsoft has made a pathway between the Linux VM and your Windows OS via the `/mnt` directory in your Ubuntu's root. 259 | 260 | Here is a quick visual of what the first few levels of any Linux filesystem look like: 261 | ![linux file system](https://curriculum-content.s3.amazonaws.com/setup-instructions/linux_fs.png) 262 | 263 | As you can see, the `mnt` directory is made for other filesystems, so that is where Microsoft connected your Linux to your Windows machine: 264 | 265 | ![linux file system](https://curriculum-content.s3.amazonaws.com/setup-instructions/linux_fs_path.png) 266 | 267 | So, you can get there from your starting point by typing: 268 | 269 | ``` 270 | cd /mnt/c/users/your_windows_username 271 | ``` 272 | or 273 | ``` 274 | cd ../../mnt/c/users/your_windows_username 275 | ``` 276 | 277 | Remember, put all of your stuff in your windows directories! That way, you have access to it via your Linux Terminal or your Windows OS, and your VSCode editor can open to the correct location when you use 278 | ``` 279 | code . 280 | ``` 281 | (if you are in your Linux file system, VSCode will open, but not to the right spot). 282 | 283 | ## Adding A Flatiron Customization To Your Terminal 284 | 285 | Start out by ensuring you're back in the Linux home directory, with `cd ~` or just `cd`. 286 | 287 | Then, make a backup for your `.bashrc` 288 | 289 | ``` 290 | mv .bashrc .bashrc.bak 291 | ``` 292 | 293 | We will want a tool for converting Windows ending to Unix endings for our new `.bashrc` 294 | 295 | ``` 296 | sudo apt-get install dos2unix 297 | ``` 298 | 299 | download the new `.bashrc` 300 | 301 | ``` 302 | curl -R "https://raw.githubusercontent.com/Enoch2k2/flatiron-wsl-bashrc/master/.bashrc" >> $HOME/.bashrc 303 | ``` 304 | 305 | We'll use our converter to convert our bashrc to use the right unix endings: 306 | 307 | ``` 308 | dos2unix .bashrc 309 | ``` 310 | ## Set up a directory for all of your labs 311 | 312 | You'll notice that we set up our `.learn-config` file earlier with a path destination of `/mnt/c/users//dev/flatiron/labs`. The `.bashrc` file we just downloaded gives us a really nice way to access that folder quickly by just typing in `labs` when we pull up our WSL terminal (or anytime you want to access that folder - it doesn't matter what directory you are currently in when you type it). In order for this to work, we need to make sure that these directories exist. To do this, begin by navigating to your `windows home` directory: 313 | 314 | ``` 315 | cd /mnt/c/users/your_windows_username 316 | ``` 317 | Now, let's make the appropriate files. Run these one at a time, and do it without copying and pasting. Remember the basic bash commands: `cd` changes directories to whatever folder you type in and `mkdir` creates a new directory which will be a subdirectory of the current directory location of your terminal. 318 | 319 | ``` 320 | mkdir dev 321 | cd dev 322 | mkdir flatiron 323 | cd flatiron 324 | mkdir labs 325 | ``` 326 | Now you have the directories you need, and you should have seen yourself navigating down your new file tree as you made each new directory and then `cd`'d into it. 327 | 328 | 329 | Now, `learn open` should work seamlessly by adding your most current lab to the `labs` directory we just made. 330 | 331 | Also, you should be able to run the command 332 | ``` 333 | labs 334 | ``` 335 | at any time in your terminal and you will be taken to your `labs` directory. Give it a try! 336 | 337 | 338 | ## Phantomjs 339 | 340 | In the Javascript section of the Flatiron curriculum, some tests require phantomjs. If you run across an error related to phantomjs, do the following: 341 | 342 | ```bash 343 | sudo apt-get update 344 | sudo apt-get install build-essential chrpath libssl-dev libxft-dev -y 345 | sudo apt-get install libfreetype6 libfreetype6-dev -y 346 | sudo apt-get install libfontconfig1 libfontconfig1-dev -y 347 | cd ~ 348 | export PHANTOM_JS="phantomjs-2.1.1-linux-x86_64" 349 | wget https://github.com/Medium/phantomjs/releases/download/v2.1.1/$PHANTOM_JS.tar.bz2 350 | sudo tar xvjf $PHANTOM_JS.tar.bz2 351 | sudo mv $PHANTOM_JS /usr/local/share 352 | sudo ln -sf /usr/local/share/$PHANTOM_JS/bin/phantomjs /usr/local/bin 353 | phantomjs --version 354 | ``` 355 | 356 | 357 | ## Advanced topics: PostgreSQL setup (OPTIONAL) 358 | 359 | **Setting up PostgreSQL allows simple production-level database integration into a Rails project. This allows easy hosting on Heroku with only a little setup.** 360 | 361 | 1) First, we want to [Download PostgreSQL for Windows](https://www.postgresql.org/download/windows/) - download the Interactive Installer. 362 | 2) Once everything is downloaded and installed, you can verify proper operation by typing in your terminal 363 | 364 | ``` 365 | psql -p 5432 -h localhost -U postgres 366 | ``` 367 | 368 | once connection is verified, you can quit by typing 369 | 370 | ``` 371 | \q 372 | ``` 373 | 374 | 3) There are a few ways to do the next few steps but the easiest way is to use pgAdmin. Open up pgAdmin, which is a Graphical User Interface for PostgreSQL. 375 | 376 | ![PGAdmin in start](https://curriculum-content.s3.amazonaws.com/setup-instructions/pgadmin-start.png) 377 | 378 | - This should open up pgAdmin in your browser. Start a server by right-clicking "PostgreSQL" and selecting "Connect Server" 379 | 380 | ![PostgreSQL selection](https://curriculum-content.s3.amazonaws.com/setup-instructions/start-server.png) 381 | ![PostgreSQL connect](https://curriculum-content.s3.amazonaws.com/setup-instructions/connect-server.png) 382 | 383 | - Enter the password you defined during the download 384 | - Your PostgreSQL server is running, and can now be integrated into your projects. 385 | - You also want to set up a new user/role and password that you want to use with your rails app. Ensure you give your user/role all available permissions during setup. 386 | - During setup, ensure to fill out `Name` in the `General` tab, `Password` in the `Definition` tab, and enable all permissions in the `Privileges` tab. 387 | 388 | ![create user](https://curriculum-content.s3.amazonaws.com/setup-instructions/pgadmin-create-user.png) 389 | 390 | ![create user permissions](https://curriculum-content.s3.amazonaws.com/setup-instructions/create-user-permissions.png) 391 | 392 | **EXAMPLE: CONNECTING YOUR POSTGRESQL SERVER TO YOUR RAILS APP** 393 | 394 | - Make sure your server is connected and roles are configured as described above. 395 | - Make sure you are in a suitable directory (in your Windows file system space) and create a Rails app configured to use PostgreSQL: 396 | ``` 397 | rails new my-first-app --database=postgresql 398 | ``` 399 | 400 | - Now, let's configure our `database.yml` file to allow our app to connect to our database. Add the following to your `config/database.yml` file under BOTH `development:` and `test:` You will need to add a user and password which will correspond to the roles we created in pgAdmin. 401 | 402 | ``` 403 | host: localhost 404 | user: your-postgres-username 405 | password: your-postgres-usernames-password 406 | ``` 407 | - We can now test our database and rails interoperability by first setting up some architecture in our app: 408 | 409 | ``` 410 | rails g scaffold Post title:string body:text 411 | ``` 412 | - now create and migrate a database: 413 | 414 | ``` 415 | rake db:create 416 | rake db:migrate 417 | ``` 418 | 419 | - If these fail, ensure you have added your database.yml configurations under both the development AND test sections 420 | 421 | - Now, start a server: 422 | ``` 423 | rails s 424 | ``` 425 | - If you navigate to `localhost:3000` you should see that we are on Rails! 426 | ![on Rails](https://curriculum-content.s3.amazonaws.com/setup-instructions/on-rails.png) 427 | - Let's test our database by going to 'localhost:3000/posts' 428 | ![posts](https://curriculum-content.s3.amazonaws.com/setup-instructions/posts.png) 429 | - Now just follow the crud links and try to make a post! We should be seeing our database working great with our rails app! 430 | 431 | ![database works](https://curriculum-content.s3.amazonaws.com/setup-instructions/database-works.png) 432 | 433 | - Hopefully, everything is working for you! Now you're ready to develop using WSL! 434 | 435 | --- 436 | 437 | ## FAQ 438 | 439 | If you get the error: `Windows Subsystem for Linux has no installed distributions. Distributions can be installed by visiting the Windows Store: https://aka.ms/wslstore Press any key to continue...` 440 | 441 | 1. Search for 'Services' in your Windows search bar, open it up 442 | 443 | ![find services ](https://curriculum-content.s3.amazonaws.com/setup-instructions/find_services.png) 444 | 445 | 2. Scroll down to the `L` section, and find `LxssManager`. If it is running, right click and `Restart` it. If it is not running, right click it and `Start` it. 446 | 447 | 448 | ![Lxss Manager](https://curriculum-content.s3.amazonaws.com/setup-instructions/lxss_manager.png) 449 | 450 | [You can check out the github issue here](https://github.com/Microsoft/WSL/issues/2576) 451 | 452 | 453 | --- 454 | ## Resources 455 | 456 | [Microsoft Documentation: Windows Subsystem for Linux]( https://docs.microsoft.com/en-us/windows/wsl/install-win10) 457 | [Setting up a SSH Key with GitHub](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/) 458 | [Basic Linux Commands](https://maker.pro/linux/tutorial/basic-linux-commands-for-beginners) 459 | --------------------------------------------------------------------------------