Appendix
Development Environment
One of the most important tasks for any aspiring developer—or any technical person generally—is setting up their computer as a development environment, making it suitable for developing websites, web applications, and other software. This appendix to Learn Enough Developer Tools to Be Dangerous, also available separately as Learn Enough Dev Environment to Be Dangerous (https://www.learnenough.com/dev-environment-tutorial), is designed to complement the main Learn Enough sequence (https://www.learnenough.com/) and the Ruby on Rails Tutorial (https://www.railstutorial.org/) by putting all of the relevant material in one place.1
1. Learn Enough Dev Environment to Be Dangerous was prepared with the help of Learn Enough cofounders Lee Donahoe and Nick Merwin.
Learn Enough Dev Environment to Be Dangerous covers several options for setting up a dev environment, aimed at readers of varying levels of experience and sophistication. If you end up using the option shown in Section A.2, there is no minimum prerequisite for this tutorial other than general computer knowledge. If you want to follow the more challenging setup in Section A.3—which we recommend most readers tackle at some point—you should have a basic familiarity with the Unix command line (as covered in Learn Enough Command Line to Be Dangerous (https://www.learnenough.com/command-line)), and a familiarity with text editors and system configuration (as covered in Learn Enough Text Editor to Be Dangerous (https://www.learnenough.com/text-editor)) is recommended.
Ebook versions of this material are available for free at learnenough.com. See the online version at learnenough.com/dev-environment (https://www.learnenough.com/dev-environment) for the most up-to-date instructions on setting up a development environment.
A.1 Dev Environment Options
Our focus in this appendix is on installing or otherwise enabling the following four fundamental tools of software development (Figure A.1):
Command-line terminal (“shell”)
Text editor
Version control (Git)
Programming languages (Ruby, etc.)
For more information on these different types of software application, see Learn Enough Command Line to Be Dangerous, Learn Enough Text Editor to Be Dangerous, Learn Enough Git to Be Dangerous (https://www.learnenough.com/git), and Learn Enough Ruby to Be Dangerous (https://www.learnenough.com/ruby).
When setting up a development environment, there are two main possibilities we recommend, listed in increasing order of difficulty:
Cloud IDE
Native OS (macOS, Linux, Windows)
Figure A.1: Typical elements of a dev environment.
If you’re relatively inexperienced, we recommend starting with the cloud IDE (Section A.2), as it has the least difficult setup process.
Native System
While the IDE option is great when you’re just getting started, eventually it’s important to be able to develop software on your native operating system (OS). Unfortunately, setting up a fully functional native development environment can be a challenging and frustrating process2—likely leaving ample opportunity to exercise your technical sophistication (Box A.1)—but it is an essential rite of passage for every aspiring technical wizard.
2. This is why it’s such a bad idea to include a native dev setup at the beginning of a book like the Ruby on Rails Tutorial (https://www.railstutorial.org/book). It’s better to get started with the core material first, and tackle the native dev environment setup later. The switch over to a cloud IDE in the third edition of the Ruby on Rails Tutorial was motivated by this realization.
In order to tackle this difficult challenge, in Section A.3 we’ll discuss native OS setup for macOS, Linux, and Windows.
A.2 Cloud IDE
The easiest dev environment option is a cloud IDE, which is an integrated development environment in the cloud that you access using the web browser of your choice. Although easy to activate, the resulting system is an industrial-grade development machine, not a toy. In addition, the cloud IDE automatically works cross-platform, since all you need is an ordinary web browser to use it (which every major OS provides).
Figure A.2: The anatomy of the cloud IDE.
There are several commercial options for running a cloud IDE, and as part of developing the Ruby on Rails Tutorial we partnered with Cloud9 (part of Amazon Web Services). The resulting environment is appropriate for Ruby on Rails web development, and as a matter of course includes all the elements mentioned in Section A.1. In particular, AWS Cloud9 comes equipped with a command-line terminal and a text editor (including a filesystem navigator), as shown in Figure A.2. Because each Cloud9 workspace provides a full working Linux system, it also automatically includes the Git version control system, as well as Ruby and several other programming languages.
Here are the steps for getting started with the cloud development environment:3
3. Due to the constantly evolving nature of sites like AWS, details may vary; use your technical sophistication (Box A.1) to resolve any discrepancies.
Because Cloud9 is part of Amazon Web Services (AWS), if you already have an AWS account you can just sign in.4 To create a new Cloud9 workspace environment, go to the AWS console and type “Cloud9” in the search box.
If you don’t already have an AWS account, you should sign up for a free account at AWS Cloud9.5 In order to prevent abuse, AWS requires a valid credit card for signup, but the workspace is 100% free (for a year as of this writing), and your card will not be charged. You might have to wait up to 24 hours for the account to be activated, but in my case it was ready in about ten minutes.
Once you’ve successfully gotten to the Cloud9 administrative page (Figure A.3), keep clicking on “Create environment” until you find yourself on a page that looks like Figure A.4. Enter the information as shown there, then make sure to choose Ubuntu Server (not Amazon Linux) (Figure A.5). Finally, keep clicking the confirmation buttons until Cloud9 starts provisioning the IDE (Figure A.6). You may run into a warning message about being a “root” user, which you can safely ignore at this early stage. (If you’re feeling up to it, you can implement the preferred method, called an Identity and Access Management (IAM) user, at this point. (See Chapter 13 in the Ruby on Rails Tutorial (https://www.railstutorial.org/book/user_microposts#sec-image_upload_in_production) for more information.)
Finally, make sure you’re running an up-to-date version of Git (Listing A.1).
Because using two spaces for indentation is a near-universal convention in Ruby, I also recommend changing the editor to use two spaces instead of the default four. As shown in Figure A.7, you can do this by clicking the gear icon in the upper right and then changing the Soft Tabs setting to 2. (Note that this takes effect immediately; you don’t need to click a Save button.)
Figure A.3: The administrative page for Cloud9.
Listing A.1: Upgrading Git (if necessary).
$ git --version # If the version number isn’t greater than 2.28.0, run the following command: $ source <(curl -sL https://cdn.learnenough.com/upgrade_git)
It’s also important to use a compatible version of Node.js (https://nodejs.org/en/):
$ nvm install 16.13.0 $ node -v v16.13.0
Finally, as of this writing the Learn Enough tutorials standardize on Ruby 2.7.4, which you can install on the cloud IDE as follows:
$ rvm install 2.7.4
Figure A.4: Creating a new work environment at AWS Cloud9.
(This uses Ruby Version Manager (https://rvm.io/), which comes preinstalled on the cloud IDE.) Once that command is finished, you can verify the Ruby version as follows:
$ ruby -v ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-linux]
(Exact version numbers may differ.)
At this point, you’re done! Although Internet access is required to use Cloud9, there is no alternative that combines so much power with such an easy setup.
Figure A.5: Selecting Ubuntu Server.
A.3 Native OS Setup
As mentioned in Section A.1, setting up your native operating system as a development environment can be challenging, but it is an important step to take once you’ve reached a certain level of technical sophistication. The cloud IDE option is a great place to start, but eventually you have to grab the bull by the horns (Figure A.8)6 and bend your native system to your will.
6. Image courtesy of Rafael Ben-Ari/Alamy Stock Photo.
Section A.3.1 covers the conversion of macOS to a fully equipped development environment, while Section A.3.2 does the same for Linux. We cover Microsoft Windows options in Section A.3.3, but (as mentioned briefly in Section A.1) this section currently defers to the cloud IDE option in Section A.2.
Figure A.6: The default cloud IDE.
A.3.1 macOS
The native Macintosh operating system, originally called Mac OS X and now known simply as macOS, has a polished graphical user interface (GUI) while being built on a solid Unix foundation. As a result, macOS is ideally suited for use as a programmer’s development environment.
The steps in this section constitute more than just a minimal system; you can actually get away with doing a lot less, but your three authors all use macOS themselves, and we feel that it’s important not to shortchange you with a half-baked setup.
Terminal and Editor
Although macOS comes with a native terminal program, we recommend installing iTerm (https://iterm2.com/downloads.html), which includes various enhancements that make it better than the default for developers and other technical users.
Figure A.7: Setting Cloud9 to use two spaces for indentation.
We also recommend installing a programmer’s text editor. There are lots of excellent choices, but the Atom editor (https://atom.io/) (covered in Learn Enough Text Editor to Be Dangerous) is a good place to start if you don’t already have a favorite.
By the way, for the Learn Enough tutorials and the Rails Tutorial, it is generally recommended that you use the Bourne-again shell (Bash) rather than the default Z shell (although it often doesn’t matter). To switch your shell to Bash, run chsh -s /bin/bash at the command line, enter your password, and restart your terminal program. Any resulting alert messages are safe to ignore. See the Learn Enough blog post “Using Z Shell on Macs with the Learn Enough Tutorials” (https://news.learnenough.com/macos-bash-zshell) for more information.
Figure A.8: Sometimes you have to grab the bull by the horns.
Xcode Command-Line Tools
Although based on Unix,7 macOS doesn’t ship with all the software necessary for a proper development environment. In order to fill this gap, macOS users should install Xcode, a large suite of development tools and code libraries created by Apple.
7. Specifically, the NeXT system developed by the company Steve Jobs founded in 1985 after being ousted from Apple. The NeXT OS became the foundation for Mac OS X (later, macOS) after Apple acquired NeXT in 1997, which also led to Jobs’ triumphant return as Apple CEO.
Xcode used to require a 4+ GB download of installation source files, but thankfully Apple has recently made Xcode incredibly quick and easy to install with a simple command-line command, as shown in Listing A.2.
Listing A.2: Installing Xcode command-line tools.
$ xcode-select --installHomebrew
The next step is technically optional, but in our view it is necessary for a truly professional-grade macOS dev environment: namely, installing the outstanding Homebrew package manager.
You can think of a package manager as an App Store that runs at the command line and is filled with free open-source software. Nowadays most Linux distributions come with a native package manager (Section A.3.2), but by default macOS doesn’t have one. Homebrew is one of many managers that is available in the open-source community, but over time it has become the most popular option among serious macOS developers.
As we’ll see in Section A.3.1, we’ll be using a program called rbenv to install Ruby, which in turn will be installed via Homebrew in Section A.3.1. But Homebrew itself requires Ruby, so it seems like we might have run into a circular dependency. Happily, macOS ships with a system Ruby that we can use to bootstrap the installation. We’ll use this default Ruby to install Homebrew, and then we’ll install rbenv and additional Ruby versions as outlined above.
The Homebrew installation program is a Bash script (https://www.learnenough.com/text-editor-tutorial/advanced_text_editing#sec-writing_an_executable_script), and can be accessed using the curl program covered in Section 3.1. We can execute the Homebrew installation script using the system bash executable, which is located in the /bin directory. The full command appears as in Listing A.3.
Listing A.3: Installing the Homebrew package manager.
$ /bin/bash -c "$(curl -fsSL https://www.learnenough.com/homebrew.sh)"
Note that Listing A.3 uses a learnenough.com forwarding URL, which points to the current Homebrew installation script. This way, if Homebrew changes the URL used to host the script, we can simply update the forwarding address, and this tutorial will continue to work as written. (You can also just copy and paste the full command from the Homebrew home page (https://brew.sh/) if you like.)
Homebrew installs a brew command-line command used for installing, updating, and removing packages. After the installation of Homebrew finishes, it’s a good idea to run brew doctor, which ensures that all of the directories and permissions needed by Homebrew to manage local files are correctly set up:
$ brew doctorIf you have any problems at this point, you’ll need to refer to the Homebrew troubleshooting wiki (https://docs.brew.sh/Troubleshooting), but you really shouldn’t unless you’ve been making changes to random system folders and permissions.
Ruby Environment (rbenv)
As we’ve just seen, macOS comes with Ruby preinstalled, but we don’t have any control over the exact version, and macOS doesn’t natively allow us to use multiple versions of Ruby in parallel. To give us more flexibility with our development environment, we’ll install rbenv, which is a utility that manages different Ruby versions and makes sure that Ruby software packages (called gems) get placed in the right spot for Ruby to find.
Using rbenv together with the associated ruby-build command also allows us to specify a different version of Ruby for different project repositories, which is a common task in software development.8 For example, an older version of a program might need an older version of Ruby to run correctly. Using rbenv means we can support such an older program while still running a more up-to-date version of Ruby for our other projects.
8. E.g., the virtualenv utility accomplishes a similar task for Python projects.
Installing rbenv is easy with Homebrew. We can install both rbenv and ruby-build in one step using brew install rbenv, as shown in Listing A.4.
Listing A.4: Installing rbenv and ruby-build.
$ brew install rbenv # automatically installs ruby-build as well
After the installation from Listing A.4 finishes, we need to get rbenv up and running using rbenv init, as shown in Listing A.5.
Note: If you’re using Zsh instead, substitute .zshrc for .bash_profile in this section. See “Using Z Shell on Macs with the Learn Enough Tutorials ” for more information.
Listing A.5: Initializing rbenv.
$ rbenv init # Load rbenv automatically by appending # the following to ~/.bash_profile (or ~/.zshrc if using Zsh): eval "$(rbenv init -)"
If Listing A.5 gives you an error message like “No such file or directory.”, try exiting your shell program with Ctrl-D and restarting it, and then try the command again. (This sort of restart-and-retry technique is classic technical sophistication (Box A.1).)
As seen in Listing A.5, running rbenv init gives us a suggestion for how to avoid having to initialize rbenv by hand each time: We simply need to append the line
eval "$(rbenv init -)"
to our Bash profile file .bash_profile (Section 5.4).
If you prefer, you can use a text editor to add the eval line to your system’s .bash_profile file, but the easiest way is to use echo and the append operator >> covered in Section 2.1, like this:
$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile # or ~/.zshrc if using Zsh
Note that we’ve included the home directory ~ in the path so that it works no matter which directory we’re currently in.
Finally, to activate the new profile file we need to source it (as seen in Listing 5.5):
$ source ~/.bash_profile # or ~/.zshrc if using Zsh
New Ruby Version
Now that rbenv is set up, let’s give it a non-system version of Ruby to manage. The installation process is handled entirely by rbenv, so all you have to do is tell it which version you’d like on your system by passing along the exact Ruby version number.
We’ll use Ruby 2.7.4 in this tutorial, which as of this writing works with a wide variety of Ruby applications, but you can also use a current or previous version as listed at the Ruby website.
To install the desired version of Ruby using rbenv, simply execute the command shown in Listing A.6. If your system ever complains that the given Ruby version isn’t available, you’ll have to update your system to access the latest version (Box A.2).
Listing A.6: Installing a fresh copy of Ruby.
$ rbenv install 2.7.4
After running the command in Listing A.6, you should see rbenv start the download process and install any dependencies that are needed for that specific version of Ruby (which might take a while depending on bandwidth and CPU limitations).
Note: You may get an error message of the form
ruby-build: definition not found: 2.7.4 See all available versions with `rbenv install --list'. If the version you need is missing, try upgrading ruby-build: brew update && brew upgrade ruby-build
If this happens, you should clone the freshest ruby-build list into the rbenv plugins directory:
$ mkdir ~/.rbenv/plugins $ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
If ruby-build is already there, you can simply pull in the latest changes:
$ cd ~/.rbenv/plugins && git pull && cd -
$ brew update $ brew upgrade
After the Ruby installation finishes, we need to tell the system that there’s a new version of Ruby using the obscurely named rehash command:
$ rbenv rehashFor this guide, we are also going to set the Ruby version from Listing A.6 as the global default so that you won’t have to worry about specifying the Ruby version when you start your project. The way to do this is with the global command:
$ rbenv global 2.7.4
At this point, it’s probably a good idea to restart your shell program to make sure all the settings are properly updated.
For future work, you may want to use specific versions of Ruby on a per-project basis, which can be done by creating a file called .ruby-version in the project’s root directory and including the version of Ruby to be used. (If it isn’t already present on your system, you’ll also have to install it using rbenv install <version number> as in Listing A.6.) See the rbenv documentation (https://github.com/rbenv/rbenv) for more information.
Finally, when installing Ruby software via gems, or self-contained packages of Ruby code, it’s often convenient to skip the installation of the local documentation, which can take more time to install than the software itself, and in any case is more conveniently accessed online. Preventing documentation installation can be done on a case-by-case basis, but it’s more convenient to make it a global default by creating a file in the home directory called .gemrc with instructions to skip the rarely used (and time-consuming to install) Ruby documentation files, as shown in Listing A.7.
Listing A.7: Configuring the .gemrc file to skip the installation of Ruby documentation.
$ echo "gem: --no-document" >> ~/.gemrc
With that configuration, any uses of gem install <gem name> to install Ruby gems will automatically be svelte, streamlined, and documentation-free.
Git
A recent version of the Git version control system should come automatically with the Xcode command-line tools installed in Section A.3.1, which you can verify using the which command:
$ which gitIf the result of this is blank, it means Git isn’t installed, and you can install it with Homebrew:
$ brew install gitEither way, you should check to make sure that the Git version number is at least 2.28.0:
$ git --version git version 2.31.1 # should be at least 2.28.0
If the version number isn’t recent enough, you should run brew update and then run brew upgrade git.
A.3.2 Linux
Because of Linux’s highly technical origins, Linux systems typically come well-equipped with developer tools. As a result, setting up a native Linux OS as a dev environment is especially simple.
Every major Linux distribution ships with a terminal program, a text editor, and Git. There are only four major steps we recommend in addition to the defaults:
Download and install Atom if you don’t already have a favorite editor.
Follow the rbenv installation instructions (https://github.com/rbenv/rbenv#installation) from the rbenv website.
Install and configure Ruby as shown in Listing A.6 and Listing A.7.
Make sure that the Git version number is at least
2.28.0.
The final step can be accomplished by running
$ git --versionIf the output isn’t at least 2.28.0, go to “Getting Started – Installing Git” (https://gitscm.com/book/en/v2/Getting-Started-Installing-Git) and install the latest version for your system.
At this point, you should be good to go!
A.3.3 Windows
Finally, we have native instructions for Microsoft Windows—or, rather, instructions for using Unix on Windows. As discussed in Section A.2, one possibility is to use a cloud IDE, but we’ve had reports of especially good results with installing Linux directly in Windows.
That’s right! Believe it or not, Windows now ships with a working Linux kernel, and you can install any of a number of Linux distributions by following Microsoft’s own instructions. (To those of us who remember the Linux-hating, predatory Microsoft of the late ’90s/early 2000s, the idea that Windows would someday ship with native Linux support is truly incredible—dogs and cats, living together!—and yet here we are.)
To get everything working, our recommendation is to follow the tutorial article “Ruby on Rails on Windows is not just possible, it’s fabulous using WSL2 and VS Code” (https://www.hanselman.com/blog/ruby-on-rails-on-windows-is-not-just-possible-its-fabulous-using-wsl2-and-vs-code) by Scott Hanselman (https://www.hanselman.com/). Although especially useful for Ruby on Rails web development, Hanselman’s tutorial is of quite general applicability, and following it should result in a fantastic general development experience on Windows.
A.4 Conclusion
If you’ve made it this far—and especially if you completed a native OS setup in Section A.3—you’ve now learned enough dev environment to be dangerous. You’re ready to move on to complete challenging tutorials like Learn Enough CSS & Layout to Be Dangerous (https://www.learnenough.com/css-and-layout), Learn Enough Ruby to Be Dangerous, and the Ruby on Rails Tutorial. Good luck!