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.
macOS macOS is a Unix-based OS, so we can simply use it as-is. Furthermore, it ships with a Terminal app by default.
Open a terminal window using the Terminal app.
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.
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 follow the installation instructions.
To install the Homebrew package manager, enter this command in the terminal:
/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”.
If you’re a first time Homebrew user, Homebrew will display instructions to set the $PATH environment variable, as well as other Homebrew-related environment variables, in a message similar to the following:
==> Next steps: |
Run the commands as instructed in your “Next steps” message.
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.
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
macOS To install VS Code using Homebrew, we enter this command in the terminal:
brew install --cask visual-studio-code |
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 . |
macOS Troubleshooting: 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:
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
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
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:
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.
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
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 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.
macOS First, to install some Ruby dependencies, we enter this command:
brew install openssl@3 libyaml gmp rust |
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.
macOS First, to install some Rails dependencies, we enter these commands:
brew install shared-mime-info |
brew install --cask chromedriver |
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
macOS To install Postgres using Homebrew, we run this command:
brew install postgresql@16 |
12.2. Start and Manage the Postgres Service
macOS To start the Postgres service, we run this command:
brew services start postgresql@16 |
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@16 |
To see detailed info about the postgresql service, we can run this command:
brew services info -v postgresql@16 |
To see the status of each service on our system (including postgresql), we can run this command:
brew services list |
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
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, 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 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. 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.