Development EnvironmentSetting Up a Computer for Rails-based Web Development

In this demonstration, I will show how to set up the full-stack Rails-based web development environment used throughout the demos.

The development environment we will use for Rails development can run on any of the most popular operating systems (Windows, macOS, and Linux). In the demo below, the following labels indicate which operating system (OS) the various demonstration steps apply to:

The development environment we set up below will be consistent across all these OSs; therefore, after this initial setup demo, OS-specific instructions will be mostly unnecessary in the remaining demos.

1. Unix-Like Environment and Terminal App

Regardless of the actual operating system (OS) we’re running on, we will use a Unix-like environment for development. A central tool in a Unix-like development environment is a terminal application, which provides, among other things, a command-line interface. The specific terminal app we will use depends on our OS.

Windows As Windows is not a Unix-based OS, we will use the Windows Subsystem for Linux (WSL) to provide an Ubuntu Linux environment (which is Unix-like). Microsoft also provides a Windows Terminal app that can be used with WSL. We broke out the steps required to set up WSL and the Windows Terminal into this separate demo. You should complete the steps in that demo before going on to the rest of this step.

When you launch the Ubuntu terminal, by default you are in the Linux home directory (~/) which is not part of the traditional Windows file system. Using the Linux file system offers many performance benefits over accessing files from a Windows directory in a Linux shell or process. However, wiping out your Linux installation will permanently delete all files in the Linux file system, and they won’t be tracked by any file backup programs for Windows. Therefore, if you want to back up your work for this class, I suggest making private Github repos (which are free to students) for all your individual assignments.

macOS macOS is Unix based, so we can simply use it as-is. Furthermore, it ships with a Terminal app by default.

Linux Although Linux is already a Unix-like OS, there are many different distributions, which can complicate things. The demos were written with Ubuntu Linux in mind; however, other Debian-based distributions may also work. Furthermore, Linux distributions generally come with a terminal app by default (with many more to choose from that can be downloaded and installed). We recommend GNOME Terminal, which we have tested and found to work well with the demos.

All For convenience, we suggest making a workspace folder in your user’s home directory to contain the projects for this class. Since we will use the command-line frequently, it will cut down on the number of times you need to change directory to get to the current project folder.

You can create the workspace folder in your user’s home directory using this command:

mkdir ~/workspace

Then, you can change directory to your workspace folder using this command:

cd ~/workspace

Important! Make sure you cd into your workspace folder before trying to do any coding assignments for this class.

2. Package Manager

Modern full-stack development platforms have numerous library and tool dependencies. To manage these dependencies, we will use a package management system, which will vary by OS.

WindowsLinux Ubuntu ships with the APT package manager by default, so there’s nothing for us to do here.

macOS We’ll use Homebrew as our package manager on macOS.

Before we can install Homebrew, we must install the latest version of Xcode. To do so, we launch the App Store, and search for “Xcode”. Then, we click the GET button for Xcode in the search results, and we follow the installation instructions.

To install the Homebrew package manager, we launch the Terminal application, and enter this command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If it asks us to install the Xcode Command Line Tools, we say “yes”.

3. Chrome

Google Chrome will be the web browser of choice for the demos. Although the demo web app should be compatible with any modern web browser, Chrome has certain development features that we will use and that are not necessarily common to all browsers.

WindowsLinux To install Chrome, we download and run the latest stable version of the installer from the Google Chrome website: https://www.google.com/chrome/.

macOS To install Chrome using Homebrew, we enter this command:

brew install --cask google-chrome

4. VS Code

Visual Studio Code (VS Code) will be the code editor of choice for the demos. It should look and work essentially the same on all OSs; however, the installation instructions vary somewhat by OS. (Note that VS Code is not the same thing as the Microsoft Visual Studio IDE.)

4.1. VS Code Installation

WindowsLinux To install VS Code, we download and run the latest stable version of the installer from the VS Code website: https://code.visualstudio.com/.

Important! When prompted to Select Additional Tasks during installation, be sure to check the Add to PATH option so you can easily open a folder in WSL using the code command in your terminal.

If you already had VS Code installed, confirm you are able to use the code command in the terminal. If the output says command not found, you can add the VS Code bin folder to the PATH manually, or simply uninstall and reinstall VS Code making sure to check the “Add to PATH” option when you install.

macOS To install VS Code using Homebrew, we enter this command:

brew install --cask visual-studio-code

If you already had VS Code installed, confirm you are able to use the code command in the terminal. If the output says command not found, follow the steps here: https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line.

4.2. VS Code Extensions

All Once we have VS Code installed, we add the following extensions, which add language-specific syntax highlighting and other features to VS Code.

Ruby/Rails Extensions:

Markdown Extensions:

Miscellaneous Extensions:

Optional Extensions:

Windows Additionally, we want to install the Remote - WSL extension which allows VS Code and WSL to interoperate.

5. Z Shell

Z Shell is the Unix shell of choice for the demos. It has a number of productivity features not found in other shells. We will use the Oh My Zsh Z Shell configuration manager, which provides a plugin and theme infrastructure for Z Shell. In addition to the features Oh My Zsh provides by default, we will also add a custom theme.

5.1. Install Z Shell

WindowsLinux To install Z Shell using APT, we enter these commands:

sudo apt update
sudo apt install zsh

macOS Since 10.15 (Catalina), Z Shell is the default shell for macOS, so we shouldn’t need to install anything.

To check that Z Shell is the current shell, you can enter a bogus command and check the first word of the output.

For example, enter this command:

monfresh

The command should return zsh: monfresh: command not found, letting us know the Z Shell is active.

5.2. Make Z Shell the Default

WindowsLinux To set Z Shell as the default shell, we enter the following command, except replacing homer with our actual username:

sudo chsh homer -s /usr/bin/zsh

To make these new settings take effect, we quit and relaunch the terminal app.

When we relaunch the terminal app, we may see this message:

This is the Z Shell configuration function for new users,
zsh-newuser-install.
You are seeing this message because you have no zsh startup files
(the files .zshenv, .zprofile, .zshrc, .zlogin in the directory
~).  This function can help you with a few settings that should
make your use of the shell easier.

You can:

(q)  Quit and do nothing.  The function will be run again next time.

(0)  Exit, creating the file ~/.zshrc containing just a comment.
     That will prevent this function being run again.

(1)  Continue to the main menu.

(2)  Populate your ~/.zshrc with the configuration recommended
     by the system administrator and exit (you will need to edit
     the file by hand, if so desired).

--- Type one of the keys in parentheses ---

We press the 2 key to select option #2.

macOS If the previous command showed zsh as the current shell, we don’t need to do anything.

5.3. Install Oh My Zsh

All To install Oh My Zsh, we enter the following command:

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.4. Add Custom Theme

All To add our custom Z Shell theme, we follow these steps.

To download the custom theme, we enter this command:

curl -fsSL --output ~/.oh-my-zsh/custom/themes/sdflem.zsh-theme https://rails-demos-n-deets-2023.herokuapp.com/resource/sdflem.zsh-theme

To open the Z Shell configuration file .zshrc in VS Code, we enter this command:

code ~/.zshrc

To configure Z Shell to use the custom theme, we locate the ZSH_THEME setting in the .zshrc file and change it to use the sdflem custom theme like so:

~/.zshrc
5
...
6
7
# Set name of the theme to load --- if set to "random", it will
8
# load a random theme each time oh-my-zsh is loaded, in which case,
9
# to know which specific one was loaded, run: echo $RANDOM_THEME
10
# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
11
ZSH_THEME="sdflem"
12
13
...
  


Caution! sdflem is the name of the theme. DO NOT replace sdflem with your own username. Make sure to save the .zshrc file.


To make the new settings take effect, we quit and relaunch the terminal app. As a result, the command prompt should now look similar to this (only with our username and hostname):


    
      
[homer@springfield:~/]
% ▊
  


Note that, for convenience, the prompt includes our Unix username (homer), the hostname of our machine (springfield), and the current working directory (~/).


6. pgAdmin 4 (Optional)


pgAdmin 4 is a database viewer and administration tool for PostgreSQL databases. This application will allow us to inspect our backend databases from a web browser.




WindowsLinux To install pgAdmin 4, we download and run the installer for the latest stable version from the pgAdmin website: https://www.pgadmin.org/download/.




macOS To install pgAdmin 4 using Homebrew, we enter this command:


    
      
brew install --cask pgadmin4
  




All Once we have installed pgAdmin 4, we confirm that the install was successful by launching the pgAdmin 4 app. A pgAdmin page should open in the web browser. The first time we launch pgAdmin, we will be prompted to create a password.


Caution! Don’t forget this password, because we will need it to run pgAdmin in the future.


7. Git


Git is a version-control system that we will use to manage different versions of the demo project as it evolves.


7.1. Git Installation


WindowsLinux Git may or may not already be installed. To check if the git package is installed, we run this command:


    
      
git --version
  


If Git is not installed (resulting in an error message instead of a version number), we install it by running this command:


    
      
sudo apt install git
  




macOS By default, macOS does not ship with Git. However, if you installed Homebrew, then Git should have been installed automatically. To check if the git package is installed, we run this command:


    
      
git --version
  


If, for some reason, Git was not installed by the Homebrew installer, you can install Git by running the following, entering your current user’s password when prompted:


    
      
sudo xcode-select --install
  


7.2. Git Configuration


All Once we have confirmed that Git is installed, we set our user Git configuration settings by creating a .gitconfig file as follows.


To create an empty .gitconfig file in our home directory, we run this command:


    
      
touch ~/.gitconfig
  


To open this file in VS Code, we enter the this command:


    
      
code ~/.gitconfig
  


We edit the contents of the file as follows, except using our own name and email:


  
  
  
    
~/.gitconfig
  
  
                
  
      
1
# This is Git's per-user configuration file.
2
[user]
3
  name = Homer Simpson
4
  email = homer@email.com
5
[core]
6
  autocrlf = false
7
[color]
8
  ui = true
9
[pull]
10
  rebase = false
  


Important! If you are familiar with Github and already have an Github account, you should use that email here. If you don’t have an account already or would like to make another account, you will be instructed to create one in the next section. The email you use to sign up with Github and the email in this file must match.


Caution! Don’t forget to save the file.


8. GitHub


GitHub is a web-based Git repository hosting service. We will use it (in conjunction with Git) to distribute different versions of the demo project as it evolves.


8.1. GitHub Account Registration


Since GitHub is a web-based service, we need to register an account via GitHub’s web interface.




All To set up our GitHub account, we register an account at https://github.com/.


Caution! Be sure that the email address registered with the GitHub account and the one in the .gitconfig file are exactly the same. These email addresses must match in order for GitHub to correctly associate commits made on our machine with our GitHub user profile. Also, we must not forget our GitHub username and password, because we will need them later!


8.2. Key-Based Authentication


Since GitHub will require us to authenticate every time we upload changes to our project, and we upload changes frequently, entering our password every time can be a hassle. SSH key authentication enables Git to automatically authenticate us using secure cryptographic keys instead of our password.




All To set up SSH key-based authentication with our Github account, we follow these steps.


To generate a new SSH key, we enter this command (replacing the email address with our own email):


    
      
ssh-keygen -t ed25519 -C "homer@email.com"
  


Important! Make sure to use the email associated with your Github account. Also, accept all the default options for that command by hitting the ENTER key without entering anything.


Troubleshooting: If you use a legacy system that does not support the Ed25519 algorithm, you can use the following command instead to generate the key with RSA:


    
      
ssh-keygen -t rsa -b 4096 -C "homer@email.com"
  


To add the key we just generated to our Github account, we copy the output of the following command (or cat ~/.ssh/id_rsa.pub if you had to use the RSA algorithm):


    
      
cat ~/.ssh/id_ed25519.pub
  


Important! Make sure you copy the entire output. It should start with ssh-ed25519 (or ssh-rsa) and end with your Github email.


After copying the key, we go to https://github.com/settings/keys in our browser, and we click the button “New SSH key”. Then, we enter a title (e.g. a name for the device), and we paste the copied key output into the key field. Finally, we click “Add SSH key”.


To check that the SSH key has been setup correctly, we enter this command:


    
      
ssh -T git@github.com
  


If it’s working correctly, the command should output a message like this:


  
  
  
    
%ssh -T git@github.com
  
  
                
  
      
Hi homer! You have successfully authenticated, but GitHub does not provide shell access.
  


9. Node.js


Modern web frontend code makes heavy use of JavaScript (JS), and as a consequence, there are numerous commonly used JS libraries and packages. Node.js provides tools for managing JS packages, so we will need to install it.




WindowsLinux To install Node.js, we run the following commands.


First, to download and run a script that prepares our system to install the Node.js package, we run this command:


    
      
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
  


Finally, to install the Node.js package, along with its dependencies, we run this command:


    
      
sudo apt-get install -y nodejs
  




macOS To install Node.js, we run this command:


    
      
brew install node
  


10. RVM


Ruby Version Manager (RVM) is a tool for managing different versions of the Ruby Programming Language and different Ruby gemsets. A gemset is the collection of Ruby gems (i.e., Ruby libraries and toolkits) used by a Ruby-based software project. We will use RVM to carefully control the version of Ruby and the associated Ruby gems that the demo project uses.


10.1. RVM Dependencies


WindowsLinux All required dependencies will be installed automatically, so there is nothing for us to do here.




macOS First, to install an RVM installer dependency, we enter this command:


    
      
brew install gnupg
  


10.2. RVM Installation


All To install RVM, we run the following commands:


    
      
curl -sSL https://rvm.io/mpapis.asc | gpg --import -
  


    
      
curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -
  


    
      
curl -sSL https://get.rvm.io | bash -s stable
  


    
      
source ~/.rvm/scripts/rvm
  


11. Ruby on Rails


Ruby on Rails (aka Rails) is a popular web-development framework and toolkit. It will provide the main platform upon which we construct the demo apps.


11.1. Ruby


As the name suggests, Rails is built using the Ruby Programming Language. Thus, Rails requires a Ruby interpreter to be installed.




All To install the latest version of Ruby, we run this command:


    
      
rvm install 3.1.2
  


To set this version of Ruby as our default version and to make the global gemset our default, we run this command:


    
      
rvm use 3.1.2 --default
  


To confirm that installation was successful, we run this command:


    
      
ruby -v
  


If Ruby has successfully installed, the output should look something like this:


  
  
  
    
%ruby -v
  
  
                
  
      
ruby 3.1.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]
  




macOS On some Macs, you may encounter an __rvm_make -j8 or __rvm_make -j10 error trying to install Ruby. This seems to be related to the openssl library version. A fix seems to be to use openssl@1.1 for the Ruby installation.


To apply this fix, run this command to install openssl@1.1:


    
      
brew install openssl@1.1
  


Then, run this command to specifically use this version to install Ruby:


    
      
rvm install 3.1.2 -- --with-openssl-dir=$(brew --prefix openssl@1.1)
  


11.2. Bundler Gem


Bundler is a Ruby gem management tool (which is itself a gem) that Rails projects use to manage their gem dependencies.




All To globally install the Bundler gem, we run this command:


    
      
rvm @global do gem install bundler
  


After this command completes, we restart the terminal to make the change take effect.




Windows If the previous command times out because RVM cannot connect to rubygems.org, we first try restarting the computer and rerunning the command.


If it still doesn’t work, the problem may be with IPv6 connections to rubygems.org. To force IPv4 connections to rubygems.org, we follow these steps.


First, we edit the /etc/gai.conf file by running:


    
      
code /etc/gai.conf
  


Then, we uncomment lines in the file, so it looks like this:


  
  
  
    
/etc/gai.conf
  
  
                
  
      
1
...
2
3
#
4
#    For sites which prefer IPv4 connections change the last line to
5
#
6
precedence ::ffff:0:0/96  100
7
8
#
9
# scopev4  <mask>  <value>
10
#    Add another rule to the RFC 6724 scope table for IPv4 addresses.
11
#    By default the scope IDs described in section 3.2 in RFC 6724 are
12
#    used.  Changing these defaults should hardly ever be necessary.
13
#    The defaults are equivalent to:
14
#
15
scopev4 ::ffff:169.254.0.0/112  2
16
scopev4 ::ffff:127.0.0.0/104    2
17
scopev4 ::ffff:0.0.0.0/96       14
  


Make sure to save the file when you are finished editing.


Finally, we try running the above rvm command again:


    
      
rvm @global do gem install bundler
  


11.3. Rails Gem


Rails is packaged as a gem that must be installed in order to create, run, and otherwise manage Rails projects.




macOS First, to install an Rails dependency, we enter this command:


    
      
brew install shared-mime-info
  




All To globally install Rails on our system, we run this command:


    
      
rvm @global do gem install rails -v 7.0.7
  


After this command completes, we restart the terminal to make the change take effect.


To verify that Rails was installed successfully, we run this command:


    
      
rails -v
  


If Rails was installed correctly, the command should output something like this:


  
  
  
    
%rails -v
  
  
                
  
      
Rails 7.0.7
  


12. Postgres


Postgres is a popular database management system. The demo Rails project will use Postgres as its database backend.


12.1. Install Postgres


WindowsLinux To install Postgres, we run these commands.


First, we add a new package repository by running this command:


    
      
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
  


Next, we get the signing key and import it by running this command:


    
      
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
  


Next, we fetch the metadata from the new repo by running this command:


    
      
sudo apt update
  


Finally, we run the command for installing the Postgres package and its dependencies:


    
      
sudo apt -y install postgresql-13 libpq-dev
  


Postgres should now be installed.




macOS To install Postgres using Homebrew, we run this command:


    
      
brew install postgresql@14
  


12.2. Start and Manage the Postgres Service


WindowsLinux To start the Postgres service, we run this command:


    
      
sudo service postgresql start
  


Windows For WSL users: The postgresql service will generally stay on all the time, but it may occasionally become halted (e.g., rebooting Windows may cause the service to halt). To restart the service, we simply rerun the above command. If in doubt, we can check the status of the service by running this command:


    
      
sudo service postgresql status
  


Additionally, we can halt the service by running this command:


    
      
sudo service postgresql stop
  




macOS To start the Postgres service, we run this command:


    
      
brew services start postgresql@14
  


The service will now generally stay on, even after reboots. If we ever need to halt the service, we can run this command:


    
      
brew services stop postgresql@14
  




Important! The following message is a common error that indicates that the Postgres service is not running, and you should run the appropriate start command for your OS:


    
      
psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
  Is the server running locally and accepting connections on that socket?
  


12.3. Configure the Postgres User Login


WindowsLinux To set up a postgres user with permission to create databases (which must have the same name as your Ubuntu user), we run the following command (replacing homer with our Unix username).


Caution! The username must match our Unix username exactly.


    
      
sudo -u postgres createuser homer -s -d
  


To set a password for our Postgres username, we run this command:


    
      
sudo -u postgres psql
  


This command will launch a postgres command prompt. At the prompt, we enter the following command (substituting homer with our Unix username and password1 with a password of our choosing):


    
      
ALTER USER homer WITH PASSWORD 'password1';
  


Caution! Don’t forget the semicolon on the end, or the command will fail silently.


Finally, we enter \q to exit the postgres prompt.




macOS To set a password for our Postgres username (same as our Unix username), we run this command:


    
      
psql postgres
  


This command will launch a postgres command prompt. At the prompt, we enter the following command (substituting homer with our Unix username and password1 with a password of our choosing):


    
      
ALTER USER homer WITH PASSWORD 'password1';
  


Caution! Don’t forget the semicolon on the end of the line, or the command will fail silently.


Enter \q to exit the postgres prompt.




All Caution! We must not forget the password we entered for our Postgres user. We will need it later to access the database using pgAdmin.


13. Conclusion


Having completed all of the above steps, our development environment should now be ready to build and run full-stack Rails-based web apps.