Setting up your development environment
Installing and using Ruby in Rails natively in Windows is a very difficult and painful process. So we will be taking the help of WSL(Windows Subsystem for Linux) for this process. WSL allows developers to run a Linux environment without the need for a separate virtual machine or dual booting. So before we get on with the installation of Ruby on Rails lets install WSL.
IMPORTANT NOTE: For installing WSL you need to have a minimum Windows version of Windows 10 version 2004 and higher (Build 18362 and higher)
Note: You can skip this step if you have already installed WSL2 on your machine.
Installing WSL
To start, enable WSL feature in windows if not already done. You can do this by opening a new PowerShell window as an administrator.
Tip: To open Powershell as an administrator, search and find PowerShell on the start menu, right click on the Microsoft PowerShell app and click on Run as Administrator.
Now execute the following command:
After this step, PowerShell might ask you to restart your machine. Let's restart out machine and continue with the installation by typing Y.
Once the system has been restarted, open a new PowerShell window and execute the command:
Note that we will be using WSL2 which is the default version of WSL in Windows machines now. If you have an older version of Windows, you might be defaulted to WSL 1 instead. To avoid this, let's specifically set the default version of WSL to be WSL2.
Once this step is done, you should reboot your system. Most of these features require a system reboot for activation since these are changes made in the system level.
If WSL has already been installed on your system, then you should see a similar message when you execute the above command:
Now you can choose your preferred distro to use along with WSL. To see a list of all available distros you can execute:
This will give you a result similar to this:
You can choose any distro you like from the list. For the rest of the guide we will be using the commands for Ubuntu. If you like to follow along with the guide, we recommend you choose the Ubuntu distro as well.
To install Ubuntu execute the command:
Some of you may face the following error:
In this case, you need to update the WSL kernal to the latest machine. For this find the architecture of your CPU. It can be found by executing the following:
For x64 machines: download and install
this update.
For ARM64 machines: download and install
this update
After installing these updates, try re-installing Ubuntu with the steps mentioned above.
After the installation, let's ensure that the distro was installed with WSL2 by executing this command:
You should get an output similar to this:
Instead, if you see that the version is one, we need to change it to version 2.
IMPORTANT NOTE: You can skip to the next step if the output you received in the line above is 2.
To change the WSL from 1 to 2 for Ubuntu, execute the following command:
If you see an error message like Please enable Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS when you open the WSL terminal, follow the below steps to fix it:
Step 1: Go to control panel > programs.
Step 2: Under the section Programs and Features click Turn windows features on or off.
Step 3: In the popup window check the box for Virtual Machine Platform and click ok.
Step 4: Restart your system if prompted.
IMPORTANT NOTE: For older systems (Windows 10 build < 19041) these steps won't work. For these versions use the following commands to install WSL. If you were able to successfully installs WSL using the steps mentioned above, you can skip these steps and start with the next section.
Step 1: Open a new PowerShell window in Administrator mode (Start menu > PowerShell > right-click > Run as Administrator)
Step 2: Enable Windows-Subsystem-Linux
Restart the machine if prompted.
Step 3: Enable the Virtual machine feature:
Step 4: Download the latest Linux kernal update package by visiting this link.
Step 5: Download the image for Ubuntu by visiting this link. Note: This link downloads the LTS version of Ubuntu. Installing this package might throw an error for some Windows users. This can be due to any of the following reasons:
- Your system doesn't support the LTS version of Ubuntu. In these cases download the version 20.04 by visiting this link instead.
- Your system has an ARM chip. In that case download the ARM version of Ubuntu by visiting this link.
- If none of these help its possible that WSL cannot be installed on your machine. Learn more by visiting this link.
Step 6: Once download is complete, open PowerShell and navigate to the directory in which the package was downloaded
Step 7: Now install the package:
Step 8: Now add the Linux distribution path to your Windows Environment PATH variables
Replace UserName with your user name.
Step 9: Once done open the Ubuntu app from the start menu
Creating a new Username and Password for UNIX
When you open the Ubuntu terminal for the first time, you will be prompted to create a new UNIX username and password. Add your desired username and password. and continue.
IMPORTANT NOTE: Make sure to note down these credentials since you will have to reinstall WSL completely if you forget them.
Install Windows Terminal (Optional)
The development experience using the Command Prompt shell, PowerShell and the WSL native terminal is subpar. To overcome this limitation, let's install the Windows Terminal.
- Go to the Windows Terminal download page and download the app.
- Install Terminal via Microsoft store.
Note: If you were able to install Windows terminal using the steps mentioned above please skip to the next section.
If your system doesn't have Microsoft store or you were not able to install the terminal using the steps mentioned above, follow these steps:
Step 1: Visit the Windows Terminal GitHub page.
Step 2: Find the latest release and click the msixbundle file to download it
Step 3: Navigate to the folder where the file was downloaded.
Step 4: Install the package
IMPORTANT NOTE: You need atleast Windows 10 2004 (build >= 10.0.19041.0) for installing Windows Terminal.
Install VSCode on your machine (Optional but recommended)
When working with WSL in Windows, we recommend using VSCode as you default text editor. This is because of the officially available Microsoft extensions in VSCode that can help you work with WSL much easier. To install VSCode follow these steps:
Step 1: Go to the VSCode page and download the latest version.
Step 2: Double click on the downloaded EXE file and install VSCode
Step 3: Now open VSCode and click to the extensions tab. There search for WSL and install the WSL extension.
Step 4: Now click on the search bar on top of your VSCode screen and type the greater than (>) symbol your keyboard to open the command palette.
Step 5: Now search and find the option WSL: Connect to WSL and click on it.
Step 6: Your VSCode window will be refreshed and you will see a WSL tag on the bottom left corner of your VSCode screen indicating you are connected to WSL.
Now you will be able to access WSL directly from your VSCode.
Installing system packages
IMPORTANT NOTE: From here on we will be executing all the commands in the WSL shell and not the Windows shells like Powershell or CMD. The WSL shell is the Ubuntu terminal in our case.
To get started with Ruby on Rails, first we need to install all the dependent system packages on the WSL. For this execute the following command within the WSL shell:
Installing zsh
We will be using ZSH as our default shell. To install and set ZSH as our default shell, follow these steps:
After the installation is complete, we need to configure zsh in our system. For the time being we will use the default configuration and build upon that. To do this execute this command on the shell:
You will be greeted with this message:
Here select option 2 which will create a .zshrc file in your home directory with the default configuration. This would be a good time to restart our terminal so that all the new changes are in effect properly.
Now that we have installed ZSH, we need to configure ZSH to be our default shell. To do this execute the following command in a new WSL shell:
Now quit and reopen your WSL terminal. You should see the ZSH shell now. But just to confirm that zsh is now you default shell, execute:
If you get the result /user/bin/zsh as your response, then that means, you have successfully installed and set ZSH as your default shell.
Setting up Oh my ZSH(OMZ) [Optional]
Oh My Zsh(OMZ) is a delightful, open source, community-driven framework for managing your Zsh configuration.
It comes bundled with thousands of helpful functions, helpers, plugins, themes, and other goodies that will make you say Oh My ...!.
To install OMZ do the following steps:
Once completed, you should get a similar output:
Now lets add the OMZ plugins that will be useful to us in the .zshrc file. To do this, you can make use of your desired text editor like VSCode or Vi. Use the following commands to edit the text file:
Now add this line to the top of your .zshrc file:
Your file should look something like this:
Once completed, save the file and restart your shell by using this command:
Doing this will auto-install all the specified plugins.
Installing Node.js
Different applications use different versions of Node.js.
Thus it is useful to be able to switch between different versions of Node.js on the fly.
At BigBinary we use Node Version Manager (nvm), which helps us maintain the correct Node.js version specific to a project, and switch between them without much hassle.
To install nvm, use the following command:
After successfully completing this step close and reopen your WSL terminal. Now let's install the proper versions of Node.JS. At BigBinary, we use node version 18.12 for our projects. So to install the proper version, use the following commands:
This will install node version 18.12.1 and set it as your default node version.
In BigBinary we use yarn as our go to package manager. So let's install yarn using this statement:
To confirm yarn installation you can check the yarn version by executing this command:
This should return a value similar of the format 1.22.22 if the installation was successful. Your yarn version might vary from the one listed here. The version of yarn doesn't matter. The only thing you have to verify is that executing the command stated above returns some version.
Install rbenv
We will be using rbenv as our Ruby version manager. To install, follow these steps:
Now lets add the rbenv paths to out .zshrc file. For this execute the following command:
Let's reload zsh by executing the following command:
Let's integrate rbenv with zsh
If all goes well, you will not see any output for this command.
Installing Ruby
Before we install Ruby, we need to make sure that build essentials is installed properly. To install build essentials, use the command:
We will be installing ruby version 3.2.2. For this execute the following command:
Now let's set the default version of ruby as 3.2.2. For this execute:
Great! You can confirm whether you have installed the right version of Ruby by executing the following command:
This should return an output similar to this:
If you're not able to get this output, try reloading zsh by executing the command source ~/.zshrc and try again. If it still throws an error, then something went wrong during your installation process and will have to start from the rbenv installation again.
Installing Rails
Now that we have Ruby up and running, its time to install Rails. For this, we will be using the gem command. Note that for this challenge, we will be installing Rails version 7.0.5. Execute this command:
Flag --no-document disables document generation.
Now install bundler which help us manage Ruby gems:
Now that we have Ruby on Rails installed, we need to install PostgreSQL as well as redis for our application to work properly.
Installing PostgreSQL
To install PostgreSQL you have to execute the following command.
Now you can start the PostgreSQL service by entering the following command:
This should give you an output similar to
Now that we have PostgreSQL up and running, lets create a new role in it so that our apps can access it. For this execute the command:
Here you should be getting a prompt asking for the details of the new role. Enter the details as follows:
Your output will look similar to this:
IMPORTANT NOTE: It is crucial that you leave the password empty.
To confirm that the new user has been created you can enter the psql console. For doing that enter the command:
You should see the PSQL console now. Here you can type the command \du to list the available roles. The role you just created should be visible on the table.
You should be able to see an output similar to the one above. You can exit from the psql terminal by entering \q.
Installing Redis
Let's install Redis now. To install, execute the following commands in a WSL shell:
This will install redis on your machine. Now quit and reopen your WSL shell. We try starting the redis server. For this, execute the command:
This should start the redis server. To confirm execute:
You should see a message similar to this:
If this throws an error or fails, then something went wrong with the redis installation. Try and install redis from start again following all the steps carefully.
You're now ready to start building with Ruby on Rails on your Windows system.
FAQ and Debugging most commonly faced problems
We have documented most of the issues faced when installing Rails in Windows in this
chapter.
Please refer this chapter to see if it solves the issues you're facing.
