Setup a Fresh Rails Project with asdf

Right now, almost half of my career was spent writing PHP code in Laravel. It was my first encounter with the MVC world, I fell in love immediately and it was easy to build products with it. The joy of putting up a quick project within minutes by the use of artisan commands and rapid scaffolding generation was definitely hard to reject as a developer. Then, I met Ruby and the mature yet reliable Rails. I discovered that the Build a blog in 15 minutes wasn't a well-known thing until DHH demonstrated how possible it is using a newly introduced web framework back in 2005. In this post, I'm going to share how a developer can spin up a fresh Ruby on Rails project with asdf in 2021.

In this setup guide, I'm working with a WSL2 + Ubuntu 20.04 environment so it might be different to yours. If you're on a UNIX-based system, that shouldn't stop you from following through. In addition, you might want to swap out that SQLite with a fresh PostgreSQL install (I'm not going to teach this now but you can search for a bunch of articles online that will help you out depending on your machine). Now, let's get started!

Let's install asdf on our machine. We need git as it is a dependency before you can get asdf so make sure you have that as well. Also, asdf has a pretty straightforward documentation so definitely check it out if you can.

First, let's clone the latest branch:

  git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.0

Then let's add it to our shell.

If you're on Bash or ZSH, add the following to your ~/.bashrc or ~/.zshrc:

  . $HOME/.asdf/asdf.sh

If you're a Fish user, add this to your ~/.config/fish/config.fish instead:

  source ~/.asdf/asdf.fish

We have to do some manual configuration of our settings for the completion feature. For Bash, add the following on your ~/.bashrc:

  . $HOME/.asdf/completions/asdf.bash

On ZSH, add these to your ~/.zshrc:

  # append completions to fpath
  fpath=(${ASDF_DIR}/completions $fpath)
  # initialise completions with ZSH's compinit
  autoload -Uz compinit
  compinit

For Fish, run the following command on your console:

  mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions

Done! That should be enough to get asdf installed on your machine. If you're having issues, check this.

Now let's go to the next step which is to install the necessary plugins to create our Rails project.

Of course, there's no Rails without Ruby so let's start with that first. In asdf, they call packages as plugins. So whenever I mention the term plugin in this section, I mean packages. 😉

Let's add our first asdf plugin via the add command:

  asdf plugin add ruby

Then let's install the latest version of Ruby via install:

  asdf install ruby latest

Afterwards, let's set our machine's global Ruby version via:

  asdf global ruby <version>
  # asdf global ruby 2.7.1

To check installed versions, just run:

  asdf list ruby

Now that we have Ruby, we also need to take care of the front-end side of things since Rails also uses webpacker so let's install both nodejs and yarn to manage our packages.

  asdf plugin add nodejs && asdf plugin add yarn

Then, proceed to add versions like how we installed Ruby earlier.

  asdf install nodejs latest && asdf install yarn latest

To check if we successfully installed the plugins, use the general command:

  asdf list

Nice, we're ready to install Rails now so let's do just that:

  gem install rails

Then let's proceed and create our new project with PostgreSQL as our database:

  rails new project-name -d postgresql

There we go! Now we have a new Rails project using asdf with PostgreSQL as the substitute database to SQLite. To test the local server, just run this within the project folder:

  rails server
  # or rails s

This should spin up your local server and now you'll be able to check your fresh Rails app on the browser via http://localhost:3000/.

That's it for this setup guide, I hope this is useful to you as it is to me. If you need additional assistance, ping me at nardparagas@gmail.com or on Twitter via @nards_paragas. I'd be happy to help out. Thanks for reading this guide!

Further Notes:

If the project shows an error on the browser saying that you're failing to connect to the database port, don't forget to start PostgreSQL via:

  sudo service postgresql start

Then if the project displays an error telling you that project-name_development database doesn't exist then run the following on your console with the project being the root:

  bundle install
  # To ensure that all required dependencies are already installed

  rails db:create
  rails db:migrate
  # To create a new local database named after your project with the _development and _test name extensions

  rails server
  # Or rails s to run your local server