Hey
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 https://github.com/theforeman/foreman
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 https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
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 127.0.0.1/32 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
exit
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.
