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.
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, |
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:
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:
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:
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:
_ __ |
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:
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:
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:
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 |
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.