Foreman development setup using linuxbrew


I am reviewing our Contributing documentation which covers development setup and I noticed that we do not cover installing proper versions of Ruby and NodeJS. While on Fedora or Red Hat systems installing particular version is piece of cake thanks to dnf modules, not all Linux distributions or operating systems have these.

While most of us use rvm and rbenv for Ruby and the latest and greatest version of node from our OS, I thought it would make sense to formalize the steps required to get Foreman running on Linux. And there is a software that can be useful for some - Homebrew. While this is meant primarily for MacOS, there is a tree caled linuxbrew which does the same things bug on Linux.

Warning: This is a tutorial for setting up custom Ruby and NodeJS versions on Linux. For similar tutorial but on MacOS see this post.

This tutorial is complementary to our Contribute guide which will focus more on standardized environment (Fedora, CentOS) and I am turning this into a wiki so feel free to update it if you want to.

Clone Foreman repository:

git clone
cd foreman

Install development packages of some key OS libraries, the following example is for Fedora or Red Hat systems:

dnf install libvirt-devel postgresql-devel openssl-devel libxml2-devel sqlite-devel libxslt-devel zlib-devel readline-devel systemd-devel libcurl-devel krb5-devel

Find out which Ruby on Rails is currently in use:

grep rails Gemfile

At the time of writing, it is Rails 6.0. Search the interned and find which Ruby version is supported, that is the supported Ruby version you should install. For Rails 6.0 it is Ruby 2.5 or 2.6 or 2.7. If any of these version is available your distribution, then stop reading right here and follow our Contributing guide to install the Ruby for your OS - there is no need to install Brew.

For NodeJS, we usually support latest stable version and likely one major version older one. At the time of writing this it is v14 and v13. If you also have this verison in your OS, there is no need to follow this guide.

Installing linuxbrew is the very same as installing homebrew, but Ruby is required. Any version will do. Perl and one Perl module is required for a dependency to build (openssl):

sudo dnf install ruby perl perl-ExtUtils-Command

Warning: This will execute shell a script downloaded from internet and install everything into $HOME/.linuxbrew:

/bin/bash -c "$(curl -fsSL"

Follow instructions on screen to add commands into your shell profile and source that file to enable the brew command. Now, install Ruby and NodeJS:

brew install ruby@2.7 node@14

Brew provides binaries for some software, but not all. Compiling Ruby takes a moment, compiling NodeJS takes about an hour. After installation instructions will be printed to add another commands to your profile - brew does not put software into PATH by default:

echo 'export PATH="$HOME/.linuxbrew/opt/node@14/bin:$PATH"' >> $HOME/.bash_profile
echo 'export PATH="$HOME/.linuxbrew/opt/ruby@2.7/bin:$PATH"' >> $HOME/.bash_profile

Source the profile (or logout and login back), in the Foreman dir perform the following commands:

bundle install --path=vendor/
npm install

If you run into compilation problems, you can add gem groups to be ignored. E.g. on my system, Ruby from linuxbrew was not picking up libvirt development library correctly. The complete list of groups which can be ignored is below, but keep in mind that excluding those will make some features unavailable:

bundle install --without="journald ec2 ovirt dynflow_sidekiq vmware openstack libvirt gce service" --path=vendor/

Install and configure PostgreSQL server, the following commands are for Fedora or Red Hat systems:

sudo dnf install postgresql
sudo postgresql-setup --initdb

I configure PostgreSQL to trust on localhost, so no password is actually needed:

# grep trust /var/lib/pgsql/data/pg_hba.conf
local   all             all                                     trust
host    all             all               trust
host    all             all             ::1/128                 trust

Create databases:

sudo systemctl enable --now postgresql
sudo su postgres -s /bin/bash
createuser -s foreman
createdb -O foreman foreman-dev
createdb -O foreman foreman-test

Configure Foreman, make sure to review and edit both files setting up database name to foreman-dev and foreman-test:

cp config/settings.yaml.example config/settings.yaml
cp config/database.yml.example config/database.yml

Migrate and seed the database and reset password which is random by default:

bundle exec rake db:migrate
bundle exec rake db:seed
be rake permissions:reset password=changeme

At this point, the development setup is be ready, you can run tests, run various rake tasks. For example, when working on template changes, you can generate snapshots to make tests passing.

RAILS_ENV=test bundle exec rake snapshots:generate

To start Ruby on Rails and Webpack via NodeJS, two processes must be started. We use “foreman” gem to start them both:

foreman start

This page is a wiki, feel free to update this as things will get old over time.

1 Like

you are a legend :slight_smile:

1 Like

Just for the record, our Contribute page will be vastly improved after my patch is merged. It describes setting up development environment on CentOS 8 and Fedora in great detail: