Development Environment Setting 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 be run on any of the most popular operating systems (Windows, macOS, and Linux), and in the demo below, the following labels denote which operating system (OS) the various demonstration steps apply to:

Windows ⇨ Steps applicable only to Windows.
macOS ⇨ Steps applicable only to macOS.
Linux ⇨ Steps applicable only to Linux.
All ⇨ Steps applicable to all OSs.

The development environment we set up below will be fairly consistent across all these OSs, and 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. There are numerous steps required to set up WSL and the Windows Terminal, so we broke them out into this separate demo.

When you launch the Linux terminal, by default you are in /mnt/c/users/[profile_name]. We don’t want to create our projects here. Instead, we want to create a workspace folder to contain our projects in the Linux home directory using this command:

mkdir ~/workspace

You can change directory to your workspace folder using this command:

cd ~/workspace

Make sure you cd into your workspace folder before trying to do any work.

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 distros, which can complicate things. The demos were written with Ubuntu Linux in mind; however, other Debian-based distros may also work. Furthermore, Linux distros 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.

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.

Windows ⇨ Linux ⇨ 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 CommandLine 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.

Windows ⇨ Linux ⇨ 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

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

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

brew install --cask visual-studio-code

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:

Ruby
VSCode Ruby (automatically installed with the Ruby extension)
Ruby Syntax Highlighting
Rails Syntax Highlighting
Simple Ruby ERB

Markdown Extensions:

Miscellaneous Extensions:

Code Spell Checker

Windows ⇨ Additionally, this extension for Windows users allows VS Code and WSL to interoperate:

Remote - WSL

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

Windows ⇨ Linux ⇨ To install Z Shell using APT, we enter this commands:

sudo apt update

sudo apt install zsh

macOS ⇨ To install Z Shell using Homebrew, we enter this command:

brew install zsh

5.2. Make Z Shell the Default

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

sudo chsh homer -s /usr/bin/zsh

macOS ⇨ To make Z Shell the default shell, we enter the following command, except replacing homer with our actual username:

sudo chpass -s /usr/local/bin/zsh homer

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

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://human-se.github.io/rails-demos-n-deets-2021/resources/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 edit the setting as follows:

ZSH_THEME="sdflem"

Caution! Don’t forget to save the 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

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.

Windows ⇨ Linux ⇨ 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

Windows ⇨ Linux ⇨ 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 ⇨ macOS ships with Git, so it should already be installed.

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:

# This is Git's per-user configuration file.
[user]
	name = Homer Simpson
	email = homer@email.com
[core]
	autocrlf = false
[color]
	ui = true
[pull]
	rebase = false

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 in lieu 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 rsa -b 4096 -C "homer@email.com"

Again, we must be sure to use the email associated with our Github account. Also, we accept all the default options for that command by hitting ENTER without entering anything.

To add the key we just generated to our Github account, we copy the output of the following command:

cat ~/.ssh/id_rsa.pub

Then, we go to https://github.com/settings/keys in our browser, and we click the button “New SSH key”. Then, we enter a title, and we paste the output of the command 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:

Hi homer! You've successfully authenticated, but GitHub does not provide shell access.

9. Node.js and Yarn

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 and Yarn provide tools for managing JS packages, so we will need to install them.

Windows ⇨ Linux ⇨ To install Node.js and Yarn, we run the following commands.

First, to install the curl command, which we’ll use to download some files from the web, we run this command:

sudo apt install curl

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

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -

Next, to prepare our system to install the Yarn package, we run these two commands:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -

echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Next, to make sure that our system is up to date with all the latest package data, we run this command:

sudo apt update

Finally, to install the Node.js and Yarn packages, along with their dependencies, we run this command:

sudo apt install nodejs yarn

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

brew install node

To install Yarn, we run this command:

brew install yarn

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

Windows ⇨ Linux ⇨ 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:

gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

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 2.7.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 2.7.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 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]

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:

sudo nano /etc/gai.conf

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

#For sites which prefer IPv4 connections change the last line to
precedence ::ffff:0:0/96 100
...
#    For sites which use site-local IPv4 addresses behind NAT there is
#    the problem that even if IPv4 addresses are preferred they do not
#    have the same scope and are therefore not sorted first.  To change
#    this use only these rules:
#
scopev4 ::ffff:169.254.0.0/112  2
scopev4 ::ffff:127.0.0.0/104    2
scopev4 ::ffff:0.0.0.0/96       14

To save our edits and exit the editor, we press Ctrl-X.

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.

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

rvm @global do gem install rails -v 6.1.0

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 6.1.0

12. Postgres

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

12.1. Install Postgres

Windows ⇨ Linux ⇨ 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-12 libpq-dev

Postgres should now be installed.

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

brew install postgresql

To update the Postgres security settings, we run this command:

curl -fsSL --output /usr/local/var/postgres/pg_hba.conf https://human-se.github.io/rails-demos-n-deets-2021/resources/pg_hba.conf

12.2. Start and Manage the Postgres Service

Windows ⇨ Linux ⇨ To start the Postgres service, we run this command:

sudo service postgresql start

For Windows/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

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

Windows ⇨ Linux ⇨ 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).

Important! 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