How to install Ruby on Rails 6.1 with asdf on macOS Big Sur

Ruby and Ruby on Rails have an outdated reputation of being difficult to set up, and some jump on this point to push their full stack JavaScript fantasies. In 2021, however, this doesn’t have to be an issue with the correct tool.

In this tutorial, we will set up Ruby on Rails 6.1 with Ruby 3, a PostgreSQL database, and Webpacker via Node on a clean install of macOS Big Sur without any pain thanks to asdf.

Step 1 - Install Homebrew #

The Missing Package Manager for macOS (or Linux)

Install Homebrew and update your $PATH. Take a look at the official documentation if you run into issues.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc
source ~/.zshrc # If you see weird behavior, restart your terminal
brew doctor
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc
source ~/.zshrc # If you see weird behavior, restart your terminal
brew doctor

If everything is set up correctly, brew doctor will return Your system is ready to brew.. Address issues if there are any as they may cause issues down the road. You may also want to set up Homebrew’s shell-completion at this time.

Step 2 - Install asdf #

Manage multiple runtime versions with a single CLI tool

Install asdf as well as some necessary dependencies and update your ~/.zshrc. If you’d like to install asdf through a different method, check out the official documentation.

We are also going to create a .asdfrc file and enable legacy_version_file, which will allow us to get version info from files like .ruby-version.

brew install coreutils curl git gpg gawk zsh yarn asdf
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc
brew install coreutils curl git gpg gawk zsh yarn asdf
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc

Restart your terminal.

Step 3 - Install Ruby #

asdf plugin add ruby
asdf install ruby 3.0.0
asdf global ruby 3.0.0
asdf plugin add ruby
asdf install ruby 3.0.0
asdf global ruby 3.0.0

Documentation

Step 4 - Install Node #

asdf plugin add nodejs
bash -c '`${ASDF_DATA_DIR:=$HOME/`.asdf}/plugins/nodejs/bin/import-release-team-keyring'
asdf install nodejs 14.16.0
asdf global nodejs 14.16.0
asdf plugin add nodejs
bash -c '`${ASDF_DATA_DIR:=$HOME/`.asdf}/plugins/nodejs/bin/import-release-team-keyring'
asdf install nodejs 14.16.0
asdf global nodejs 14.16.0

Documentation

Step 5 - Install Postgres #

asdf plugin add postgres
asdf install postgres 13.2
asdf global postgres 13.2
$HOME/.asdf/installs/postgres/13.2/bin/pg_ctl -D $HOME/.asdf/installs/postgres/13.2/data -l logfile start
asdf plugin add postgres
asdf install postgres 13.2
asdf global postgres 13.2
$HOME/.asdf/installs/postgres/13.2/bin/pg_ctl -D $HOME/.asdf/installs/postgres/13.2/data -l logfile start

Documentation

🔥 You can add this handy function to your ~/.zshrc from Josh Branchaud to make switching postgres versions easier.

Step 6 - Create Ruby on Rails app #

To make sure everything’s correct, let’s create a new Rails app with a postgres database:

gem install bundler rails
rails new asdf_demo -d postgresql
cd asdf_demo
bin/rails db:prepare
bin/rails s
gem install bundler rails
rails new asdf_demo -d postgresql
cd asdf_demo
bin/rails db:prepare
bin/rails s

Open localhost:3000 in your browser and you should see the Rails welcome screen. 🥳

Summary #

In the end, this was all we needed to get a Rails app running on a clean install of macOS Big Sur:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc
source ~/.zshrc
brew doctor
brew install coreutils curl git gpg gawk zsh yarn asdf
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc
# ⚠️ Restart your terminal ⚠️
asdf plugin add ruby
asdf install ruby 3.0.0
asdf global ruby 3.0.0
asdf plugin add nodejs
bash -c '`${ASDF_DATA_DIR:=$HOME/`.asdf}/plugins/nodejs/bin/import-release-team-keyring'
asdf install nodejs 14.16.0
asdf global nodejs 14.16.0
asdf plugin add postgres
asdf install postgres 13.2
asdf global postgres 13.2
$HOME/.asdf/installs/postgres/13.2/bin/pg_ctl -D $HOME/.asdf/installs/postgres/13.2/data -l logfile start
# ⚠️ Restart your terminal ⚠️
gem install bundler rails
rails new asdf_demo -d postgresql
cd asdf_demo
bin/rails db:prepare
bin/rails s
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.zshrc
source ~/.zshrc
brew doctor
brew install coreutils curl git gpg gawk zsh yarn asdf
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc
# ⚠️ Restart your terminal ⚠️
asdf plugin add ruby
asdf install ruby 3.0.0
asdf global ruby 3.0.0
asdf plugin add nodejs
bash -c '`${ASDF_DATA_DIR:=$HOME/`.asdf}/plugins/nodejs/bin/import-release-team-keyring'
asdf install nodejs 14.16.0
asdf global nodejs 14.16.0
asdf plugin add postgres
asdf install postgres 13.2
asdf global postgres 13.2
$HOME/.asdf/installs/postgres/13.2/bin/pg_ctl -D $HOME/.asdf/installs/postgres/13.2/data -l logfile start
# ⚠️ Restart your terminal ⚠️
gem install bundler rails
rails new asdf_demo -d postgresql
cd asdf_demo
bin/rails db:prepare
bin/rails s

I am sure there are ways to improve this and I would love to hear any optimizations you come up with!

It doesn’t have to end here though! Checkout asdf’s plugin list for all available plugins. Redis, Elasticsearch, and ImageMagick can all be managed through asdf.

Hopefully this tutorial will help you get up and running with a Ruby on Rails 6.1 development environment lightning fast and pain free. 🚀

Happy coding!