Setting Up the Development Environment
In this demonstration, I will show how to set up the development environment used throughout the demos. We will use a Unix-like environment, regardless of the operating system being run. As a consequence, some of the setup will be different based on your computer’s operating system (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).
-
macOS ⇨ As macOS is already a Unix-based OS, we will simply use it as-is.
-
Linux ⇨ Although Linux is already a Unix-like OS, there are numerous different distros, which can complicate things. The demos were written with Ubuntu Linux in mind; however, other Debian-based distros may also work.
In the text below, we use badges similar to the ones above to denote which instructions apply to which OS. Following this initial setup demo, OS-specific instructions will be much fewer are farther between.
1. Unix-Like Environment and Terminal App
As mentioned above, the demos will use a Unix-like development environment, although the exact environment will vary by OS. The main interface for such environments are terminal applications, which will similarly vary by OS.
-
Windows ⇨ Set up the Windows Subsystem for Linux (WSL) and install the Windows Terminal app. To do so, follow the steps in this demo: Setting Up Windows Subsystem for Linux (WSL) and Windows Terminal.
-
macOS ⇨ No action needed. macOS is Unix based and ships with a Terminal app by default.
-
Linux ⇨ No action needed. Linux is Unix based and generally comes with a terminal app (with many more to choose from). We recommend GNOME Terminal, because we have tested and which worked well for 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 ⇨ No action needed. Ubuntu ships with the APT package manager by default.
-
macOS ⇨ Install the Homebrew package manager by following these steps:
-
Launch the Terminal application and enter this command:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-
When it asks you to install Xcode CommandLine Tools, 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 ⇨ Download and install the latest stable version from the Google Chrome website: https://www.google.com/chrome/.
-
macOS ⇨ Install using Homebrew by entering this command:
brew cask install 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 ⇨ Download and install the latest stable version from the VS Code website: https://code.visualstudio.com/.
-
macOS ⇨ Install using Homebrew by entering this command:
brew cask install visual-studio-code
4.2. VS Code Extensions
- All ⇨ Once you have VS Code installed, add the following extensions:
- Code Spell Checker
- Markdown PDF
- Markdown Preview Github Styling
- markdownlint
- Simple Ruby ERB
- (Windows users only) 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 ⇨ Install Z Shell using APT by entering the following commands:
sudo apt update sudo apt install zsh
-
macOS ⇨ Install Z Shell using Homebrew by entering the following command:
brew install zsh
5.2. Make Z Shell the Default
-
Windows/Linux ⇨ Make Z Shell the default shell by following these steps.
-
Set Z Shell as the default shell by entering the following command, except replacing
homer
with your username:sudo chsh homer -s /usr/bin/zsh
-
Quit and relaunch the terminal app to make the new settings take effect.
-
-
macOS ⇨ Make Z Shell the default shell by following these steps.
-
Set Z Shell as the default shell by entering the following command, except replacing
homer
with your username:sudo chpass -s /usr/local/bin/zsh homer
-
Quit and relaunch the terminal app to make the new settings take effect.
-
5.3. Install Oh My Zsh
-
All ⇨ Install Oh My Zsh by entering the following command:
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
5.4. Add Custom Theme
-
All ⇨ Add our custom Z Shell theme by following these steps.
-
Download the custom theme by entering this command:
curl -fsSL --output ~/.oh-my-zsh/custom/themes/sdflem.zsh-theme https://human-se.github.io/rails-demos-n-deets-2020/resources/sdflem.zsh-theme
-
Open the Z Shell configuration file
.zshrc
in VS Code by entering this command:code ~/.zshrc
-
Configure Z Shell to use the custom theme by locating the
ZSH_THEME
setting in the.zshrc
file and editing the setting as follows:ZSH_THEME="sdflem"
Don’t forget to save the file!
-
Quit and relaunch the terminal app to make the new settings take effect. You should now see a command prompt that looks similar to this (only with your 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 ⇨ Download and install the latest stable version from the pgAdmin website: https://www.pgadmin.org/download/).
-
macOS ⇨ Install using Homebrew by entering this command:
brew cask install pgadmin4
-
All ⇨ Once you have installed pgAdmin 4, confirm that the install was successful by launching the pgAdmin 4 app. A pgAdmin page should open in your web browser. The first time you launch pgAdmin, you will be prompted to create a password.
Caution! Don’t forget your pgAdmin password, because you 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. Check if the git package is installed by running this command:
git --version
If Git is not installed (resulting in an error message instead of a version number), install it by running:
sudo apt install git
-
macOS ⇨ Git should already be installed, because macOS ships with it.
7.2. Git Configuration
-
All ⇨ Once you have confirmed that Git is installed, set your user Git configuration settings by creating a
.gitconfig
file as follows:-
Create an empty
.gitconfig
file in your home directory by running this command:touch ~/.gitconfig
-
Open this file in VS Code by entering the this command:
code ~/.gitconfig
-
Edit the contents of the file as follows, except using your 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
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 will need to register an account via GitHub’s web interface.
-
All ⇨ Set up your GitHub account by following these steps.
-
Register an account at https://github.com/ (if you don’t already have).
Caution! Be sure that your GitHub account is set up with the same email address that you use in your
.gitconfig
file. The emails must match in order for GitHub to associate your commits with your GitHub user profile.Also, be sure not to lose your GitHub username and password.
-
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 ⇨ Set up SSH key-based authentication with your Github account by following these steps.
-
Generate a new SSH key using this command (replacing the email address with your own):
ssh-keygen -t rsa -b 4096 -C "homer@email.com"
Again, be sure to use the email associated with your Github account. Also, you should accept all the default options for that command by hitting ENTER without entering anything.
-
Add the key you just generated to your Github account by copying the output of the following command:
cat ~/.ssh/id_rsa.pub
Then, go to https://github.com/settings/keys in your browser. Make sure you are logged into Github. Click the button “New SSH key”, enter a title, and paste the output of the command in the key field. Click “Add SSH key”.
-
Check the SSH key has been setup correctly by entering this command:
ssh -T git@github.com
You should get a message like:
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
-
Windows/Linux ⇨ Install Node.js and Yarn by running the following commands:
sudo apt install curl curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - 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 sudo apt update sudo apt install zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev nodejs yarn
-
macOS ⇨ Install Node.js and Yarn by running the following commands:
brew install node 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 ⇨ First, install several of RVM’s dependencies by entering this command:
sudo apt install libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
-
macOS ⇨ First, install an RVM installer dependency by entering this command:
brew install gnupg
10.2. RVM Installation
-
All ⇨ Install RVM by running 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 app.
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 ⇨ Install the latest version of Ruby by running each of the following commands:
rvm install 2.6.5 rvm use 2.6.5 --default ruby -v
If Ruby has successfully installed, the output of
ruby -v
should be something like:ruby 2.6.5p114 (2019-10-01 revision 67812) [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 ⇨ Globally install the Bundler gem by running this command:
rvm @global do gem install bundler
-
Windows ⇨ If the previous command times out because RVM cannot connect to
rubygems.org
, try restarting the computer and rerunning the command. If it still doesn’t work, the problem may be with IPv6 connections torubygems.org
. Force IPv4 connections torubygems.org
by following these steps and then trying the command again:-
Edit the /etc/gai.conf file by running:
sudo nano /etc/gai.conf
-
Uncomment lines to match the following:
#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
-
Enter Ctrl-X to save and exit.
-
11.3. Rails Gem
Rails is packaged as a gem that must be installed in order to create, run, etc. Rails projects.
-
All ⇨ Globally install Rails by running this command:
rvm @global do gem install rails
Verify that Rails was installed successfully by running this command:
rails -v
It should display version 6.0.2.1.
12. Postgres
Postgres is a popular database management system. The demo Rails project will use Postgres as its database backend.
-
Windows/Linux ⇨ Install Postgres by following these steps:
-
Install the Postgres packages by running:
sudo apt -y install postgresql-12 postgresql-client-12 libpq-dev
If the
postgresql-12
package cannot be found, follow these additional steps, and then try the above command again:-
Add the repository by running:
sudo tee /etc/apt/sources.list.d/pgdg.list <<END deb http://apt.postgresql.org/pub/repos/apt/ bionic-pgdg main END
Be careful when you copy and paste the above command that you do not get an extra space before the
END
line. -
Get the signing key and import it by running:
wget https://www.postgresql.org/media/keys/ACCC4CF8.asc sudo apt-key add ACCC4CF8.asc
-
Fetch the metadata from the new repo by running:
sudo apt update
-
-
Start the Postgres service by running:
sudo service postgresql start
For Windows/WSL users, the
postgresql
service will generally stay on, but you may sometimes discover that it has been halted (e.g., rebooting Windows may cause the service to halt). To restart the service, simply rerun the above command. If in doubt, you can check the status of the service by running this command:sudo service postgresql status
Additionally, you can halt the service by running this command:
sudo service postgresql stop
-
Set up a
postgres
user with permission to create databases (which must have the same name as your Ubuntu user) by running the following command (replacinghomer
with your Unix username).Important! The username must match your Unix username exactly.
sudo -u postgres createuser homer -s -d
-
Set a password for your Postgres username by running:
sudo -u postgres psql
This command will launch a
postgres
command prompt. At the prompt, enter the following command (substitutinghomer
with your Unix username andpassword1
with a password of your choosing):ALTER USER homer WITH PASSWORD 'password1';
Caution! Don’t forget the semicolon on the end, or the command will fail silently.
-
Enter
\q
to exit thepostgres
prompt.
-
-
macOS ⇨ Install Postgres by following these steps:
-
Install the Postgres packages using Homebrew by running this command:
brew install postgresql
-
Update the Postgres security settings by running the following command:
curl -fsSL --output /usr/local/var/postgres/pg_hba.conf https://human-se.github.io/rails-demos-n-deets-2020/resources/pg_hba.conf
-
Start the Postgres service by running:
brew services start postgresql
The service will now generally stay on, even after reboots. If you ever need to halt the service, you can run this command:
brew services stop postgresql
-
Set a password for your Postgres username (same as your Unix username) by running:
psql postgres
This command will launch a
postgres
command prompt. At the prompt, enter the following command (substitutinghomer
with your Unix username andpassword1
with a password of your choosing):ALTER USER homer WITH PASSWORD 'password1';
Caution! Don’t forget the semicolon on the end, or the command will fail silently.
-
Enter
\q
to exit thepostgres
prompt.
-
-
All ⇨ Caution! Don’t forget the password you entered for your Postgres user. You will need it later to access the database using pgAdmin.
13. Conclusion
Having completed all of the above development environment setup, the next step will be to test that it’s all working by running an existing Rails-based web app.