Have you always wanted to create an awesome Ruby on Rails application, but don’t know where to get started? This article can be a great starting point.
This article can serve as a reference for people on Ubuntu-based systems who need a Ruby on Rails setup from scratch.
Introduction
In order to be able to follow along, it is advised that you know how to use the Ubuntu terminal. I will try to make it as comprehensive as possible, and largely this is just a copy‑paste exercise, but you might run into issues that require some knowledge of working in a Linux terminal.
This installation guide will work for Windows Subsystem for Linux as well. Recently I installed Ruby on Rails on Ubuntu for WSL and the process was identical to the one described in this article, so you can just follow along. All you would need to do is set up Ubuntu on WSL first and open a terminal, then you are good to go.
As I have done this process a lot of times over the years, I am aware that between Linux distributions and different versions, there are sometimes issues that arise with packages missing or other strange errors.
These errors can often be solved by asking Google or ChatGPT, as well as reading Stack Overflow solutions. This will make you a more seasoned developer as you will run into a lot of these issues in your career, and being able to solve those by doing research yourself is one of the most essential skills you should have.
However if you get stuck or really can’t figure it out, feel free to leave a comment on this article.
Part 1: Preparing our system
First, we need to make sure we are up to date on our packages. Simply run:
sudo apt-get update sudo apt-get upgrade -y
Then, we want to make sure we are in our home folder as we do all of these installations. We can navigate to our home folder by running:
cd ~
Part 2: Setting up Ruby
In order to use Ruby on Rails, we need to have a working installation of Ruby.
It is highly advised to use a version manager, which is a tool that can switch Ruby versions easily based on which project you’re on. This will make upgrading as well as managing multiple projects a lot easier, as you can just have both versions installed and switch between them.
My package manager of choice is asdf, as I have had the least issues with it over time, and the fact that it supports other languages than Ruby (such as Node.js) is a strong plus. Other options are rbenv or rvm, which I will not discuss here.
To start, we will need to install a few system packages needed to compile Ruby (and dependencies):
sudo apt-get update sudo apt-get install -y git-core 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 autoconf bison
Then, clone asdf:
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.12.0
Next, set up your shell environment for asdf. If you use bash, add:
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc echo 'legacy_version_file = yes' >> ~/.asdfrc
If you use zsh, put equivalent lines in ~/.zshrc, using the zsh completions file.
Open a new terminal window (or source ~/.bashrc / source ~/.zshrc) so these changes take effect.
Now, make sure asdf’s Ruby plugin is up to date, then install Ruby:
asdf plugin add ruby asdf plugin update ruby asdf install ruby latest asdf global ruby latest
This selects the latest stable Ruby version (for example, Ruby 3.3.x or the newest 3.x as of 2025).
You can verify:
which ruby ruby -v
Part 3: Setting up Node.js
Rails 8’s modern JS tooling expects you to have a JavaScript runtime available (e.g. Node). You can also manage that via asdf:
asdf plugin add nodejs asdf install nodejs latest asdf global nodejs latest
Verify:
which node node -v
Optionally, in 2025 many Rails developers also choose bun, pnpm, or esbuild for faster JS tooling—but the default Rails 8 setup leans toward Importmaps + Propshaft (no bundler) unless you explicitly choose otherwise.
Part 4: Setting up a PostgreSQL server
Install PostgreSQL and development headers:
sudo apt-get install -y postgresql postgresql-contrib libpq-dev
Then switch to the postgres user and enter the psql shell:
sudo -u postgres psql
Inside psql, run:
CREATE USER dev_rails WITH SUPERUSER LOGIN CREATEDB PASSWORD 'dev';
Then exit:
\q
Part 5: Installing Ruby on Rails
First, update RubyGems:
gem update --system
Then install Rails (Rails 8 is the current major version as of 2025):
gem install rails
You can also pin to a specific version, e.g.:
gem install rails -v 8.0.0
Verify:
rails -v
Part 6: Creating a new Ruby on Rails project
Navigate to the directory where you want your new project. For simplicity:
cd ~
Now run the rails new command. In Rails 8, the default JavaScript setup is importmap + Propshaft (i.e. no bundler).
Here’s a default Rails 8 create command:
rails new ruby_on_rails_example -d postgresql cd ruby_on_rails_example
If you explicitly want to use Webpack (or another bundler), you can pass:
rails new ruby_on_rails_example -d postgresql -j webpack
or
rails new ruby_on_rails_example -d postgresql -j esbuild
Part 7: Configuring Ruby on Rails for PostgreSQL
We need to configure the database.yml file so Rails can connect to your local Postgres user.
Open config/database.yml, find the development: section and update it to include:
development: <<: *default database: ruby_on_rails_example_development host: localhost username: dev_rails password: dev
Then find the test: section and similarly adjust:
test: <<: *default database: ruby_on_rails_example_test host: localhost username: dev_rails password: dev
Now run:
rails db:create
Part 8: Configuring JavaScript / Asset handling
In Rails 8, the default JavaScript and asset setup uses importmap-rails + Propshaft. You don’t necessarily need Webpack or other bundlers unless you plan on heavy JS dependencies.
If you later decide to use bundling tools (webpack, esbuild, bun, vite, etc.), you can combine them with importmap in more advanced setups.
Make sure, if you are using a bundler, you run:
npm install
to install all JS dependencies.
Part 9: Starting your server
At this point, you're ready to run your Rails app.
rails server
You should see output like:
=> Booting Puma
=> Rails 8.0.x application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Listening on http://127.0.0.1:3000
Use Ctrl-C to stop
Navigate to http://localhost:3000 and you should see the Rails welcome page.
Part 10: Start developing
I hope you enjoyed the guide, and have learned something in the process as well.
Now you are ready to build an awesome Ruby on Rails project. Stay tuned for more exciting guides on how to continue your Rails journey.
I have committed the end result of this article to a GitHub repository. If you can’t get things set up properly, you could try cloning that repository, though it is much better to be able to set it all up yourself.
And hopefully much more! 🙂
If you liked this article, make sure to check out InstaSupport, it's free support software ideal for indie developers starting out!