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), but the setup process is different for each OS.

After this initial setup demo, the development environment will be consistent across all these OSs; therefore, OS-specific instructions will be mostly unnecessary in the remaining demos.

Choose your operating system:

1. Unix-Like Environment and Terminal App

Regardless of the actual operating system (OS) your machine uses, 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. A command-line interface (CLI) is a means of interacting with a computer program or operating system by inputting lines of text called command-lines, or commands.

The specific terminal app we will use depends on our OS, but all terminal apps will be able to interact with the Unix-like development environment using similar commands in the CLI.


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.

Complete the steps in the "Windows Subsystem for Linux" demo to set up Ubuntu in WSL and install Windows Terminal before continuing with this demo.

Open an Ubuntu terminal window using the Windows Terminal app if you don’t already have one open.

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.

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.

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.

The official instructions for installing Chrome on all platforms are available at https://support.google.com/chrome/answer/95346?hl=en&co=GENIE.Platform%3DDesktop and are summarized below. If you encounter any issues with the following instructions, please refer to the official documentation.


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/.

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.

All After you complete the installation or (if you already had VS Code installed), confirm you are able to open a VS Code window from the terminal by entering the following command in the terminal:

code .

WindowsLinux Troubleshooting: 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.

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

5.2. Make Z Shell the Default

WindowsLinux To set Z Shell as the default shell, we enter the following command, 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.

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 (except 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/.


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

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 replacing Homer’s name and email with our own:

~/.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
  editor = nano
8
[color]
9
  ui = true
10
[pull]
11
  rebase = false
12
[init]
13
  defaultBranch = main

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 exactly. You should use your real name, not your username, for the name setting.

Don’t forget to save the file.

To make sure the contents of the file have been added correctly, run the following command to print the contents to the terminal:

cat ~/.gitconfig

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 Homer’s email with our actual 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 by hitting the ENTER key 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_ed25519.pub

Important! We make sure to copy the entire output. It should start with ssh-ed25519 and end with our 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

The first time we run the command it might say something like Are you sure you want to continue connecting (yes/no/[fingerprint])?. We enter yes.

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. mise Development Environment Setup Tool

We will use the mise tool to manage different versions of the Ruby Programming Language and Node.js.

All To install mise, we run this command:

curl https://mise.run | sh

To activate mise, we run this command:

echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

To start mise working, we restart the terminal.

After restarting the terminal, to test that mise is working correctly, we run this command:

mise version

If mise is working correctly, the output should look something like this:

              _                                        __
____ ___ (_)_______ ___ ____ ____ / /___ _________
/ __ `__ \/ / ___/ _ \______/ _ \/ __ \______/ __ \/ / __ `/ ___/ _ \
/ / / / / / (__ ) __/_____/ __/ / / /_____/ /_/ / / /_/ / /__/ __/
/_/ /_/ /_/_/____/\___/ \___/_/ /_/ / .___/_/\__,_/\___/\___/
/_/
2025.1.3 macos-arm64 (bc1fa08 2025-01-09)

10. 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.


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

mise use --global node@22.11.0

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

node --version

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

%node --version
v22.11.0

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.


WindowsLinux First, to install some Ruby dependencies, we enter this command:

sudo apt install build-essential rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev

All To install our preferred version of Ruby, we run this command:

mise use --global ruby@3.3.6

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

ruby --version

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

%ruby --version
ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin24]

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 ensure that RubyGems is up to date, we run this command:

gem update --system

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

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.


WindowsLinux First, to install some Rails dependencies, we enter this command:

sudo apt install ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils chromium-chromedriver -y

All To globally install Rails, we run this command:

gem install rails --version 7.1.5.1

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

rails --version

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

%rails --version
Rails 7.1.5.1

Troubleshooting: If the rails command is not found, restarting the terminal may correct the issue.

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 the command for installing the Postgres package and its dependencies:

sudo apt install postgresql libpq-dev

PostgreSQL 16 should now be installed.

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

Troubleshooting: 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 actual 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, replacing homer with our actual 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.


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. Create Workspace Folder

All For convenience, we make a workspace folder in our home directory to contain our project code.

To create the workspace folder in our home directory, we enter this command in the terminal:

mkdir ~/workspace

To change directory into our workspace folder, we enter this command in the terminal:

cd ~/workspace

Important! Always be sure to cd into the workspace folder before cloning a repo or creating a new project.

14. 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.