Skip to content

Latest commit

 

History

History
299 lines (238 loc) · 9.92 KB

foreman_dev_setup.asciidoc

File metadata and controls

299 lines (238 loc) · 9.92 KB
Raw

Install From Source

Table of Contents

Prerequisites

Please refer to the .github/matrix.json file in the project repository to find the latest supported versions for Ruby, NodeJS, and PostgreSQL. This file is regularly updated to reflect our current support.

We recommend using PostgreSQL 12+.

If you’re using NPM version 7.x or higher, you will need to use the --legacy-peer-deps flag when installing npm packages. This is due to changes in how NPM handles peer dependencies from version 7 onwards.

rbenv or RVM can be used to install compatible Ruby versions. Similarly, nvm can be used to manage node and npm on your system.

Fedora

Fedora ships with a too new Ruby. It’s recommended to install rbenv to install a compatible version:

sudo dnf install rbenv ruby-build-rbenv nodejs
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
rbenv install 2.7.6

RVM can also be used.

Enterprise Linux 8

By default EL8 ships with older versions, but newer modules are available:

dnf module enable ruby:2.7
dnf module enable postgresql:12
dnf module enable nodejs:14

Now install the development packages:

dnf groupinstall "Development Tools" "Development Libraries"
dnf -y install gcc-c++ git ruby ruby-devel rubygem-bundler \
    libvirt-devel postgresql-devel openssl-devel \
    libxml2-devel libxslt-devel zlib-devel \
    readline-devel systemd-devel tar libcurl-devel nodejs

PostgreSQL

Use the following steps to set up PostgreSQL on RPM based distributions:

sudo dnf install postgresql
sudo postgresql-setup --initdb
sudo -u postgres createuser --createdb $USER

Setting the repository

# On Github create your own fork
git clone https://github.com/{GITHUB_USER}/foreman.git -b develop
cd foreman
cp config/settings.yaml.example config/settings.yaml
cp config/database.yml.example config/database.yml
git remote add upstream [email protected]:theforeman/foreman.git

If you’re using rbenv, now you can configure it to locally use Ruby 2.7:

rbenv local 2.7.6

Now you can install the dependencies:

bundle install
npm install

  • In case you get this error: …​ An error occurred while installing pg (PG_VERSION), and Bundler cannot continue. Make sure that gem install pg -v '{PG_VERSION}' --source 'https://rubygems.org/' succeeds before bundling. …​

  • In case you get this error while bundle install caused by ruby-libvirt gem: extconf.rb:37:in `<main>': libvirt library not found in default locations (RuntimeError). Try to find the pkgconfig, it may be in a different location than /usr/lib64/pkgconfig. Try to use this command: export PKG_CONFIG_PATH=/usr/lib64/pkgconfig.

Run the following command:

gem install pg -v '{PG_VERSION}' -- --with-pg-config=/usr/pgsql-13/bin/pg_config

Good to Notice: Foreman uses Bundler to install dependencies and get up and running. This is the preferred way to get Foreman if you want to benefit from the latest improvements. By using the git repository you can also upgrade more easily.

Setting the database

It is important that config/database.yml is set to use the correct database in the “development” block. Rails (and subsequently Foreman) will use these connection settings under “development” to manage the database it uses and setup the necessary schema.

Set up database schema:

bundle exec rake db:create # if not already created
bundle exec rake db:migrate
SEED_ADMIN_PASSWORD=changeme bundle exec rake db:seed

The previous commands will create databases only for the development environment, for test environment you need to run also:

RAILS_ENV=test bundle exec rake db:create
RAILS_ENV=test bundle exec rake db:migrate

Running Foreman

In order to run Foreman you can use the following command inside your git repository:

bundle exec foreman start

You can also run Foreman in two separate processes - frontend and rails. This way when you need to restart Foreman (for code reload) you don’t have to wait for webpack build:

# Rails
bundle exec rails s -b 0.0.0.0 -p 3000

# Frontend
bundle exec foreman start webpack

Note: You could also create a .env file which lets you customize your individual working environment variables. NOTIFICATIONS_POLLING and REDUX_LOGGER are options that can be set in an .env file (as well as in the cli call). REDUX_LOGGER has a boolean value which controls if Foreman will print each redux call in the web console, and NOTIFICATIONS_POLLING is the notification polling interval in ms.

Resetting password

If you can’t find your admin user’s password, you can update its password from rails console:

bundle exec rake permissions:reset password=changeme

Now you can login with admin user and its new password.

Seeding mock data

bundle exec rake seed:forgeries

All rake tasks are available with the following command:

bundle exec rake -T

Running tests in Foreman

Make sure to run tests from the Foreman directory.

RuboCop Tests

To run RuboCop test, use the following command:

bundle exec rubocop [<path_to_file>]

You can also run RuboCop in an autocorrect mode, where it will try to automatically fix the problems it found in your code:

bundle exec rubocop --auto-correct # (only when it's safe)
bundle exec rubocop --auto-correct-all # (safe and unsafe)

Foreman Tests

To run Foreman’s tests:

bundle exec rake test [TEST=<path_to_file>]

To run a specific test:

bundle exec rails test <path_to_file>:<test_line_number>
Foreman Integration Tests

To run Foreman’s integration tests you need to have ChromeDriver installed on your machine.

Foreman’s integration tests use the Capybara test framework. For more information about the Capybara DSL check out the Capybara API.

Adding DEBUG_JS_TEST=1 to the test run, will open a web browser and run the tests in chrome.

To run Foreman’s integration tests:

npm install # make sure to install npm dependencies for webpack
bundle exec rake webpack:compile
bundle exec rake test TEST=test/integration/<test_file> [DEBUG_JS_TEST=1]

Debugging Foreman with Pry

Pry is a runtime developer console and IRB (interactive Ruby) alternative with powerful introspection capabilities. You can use use Pry as a developer console or as a debugger. Pry gem is required by Foreman, meaning that Bundler installs it for you.

To invoke the debugger, place binding.pry somewhere in your code as follows:

require 'pry'; binding.pry

When the Ruby interpreter hits that code, execution stops, and you can type in commands to debug the state of the program.

Useful Pry Commands

  • pry -Opens the Pry console in your terminal

  • exit -Exits current loop

  • exit! -Exits Pry console

Stepping

To step through the code, you can use the following commands:

  • break: Manage breakpoints.

  • step: Step execution into the next line or method. Takes an optional numeric argument to step multiple times.

  • next: Step over to the next line within the same frame. Also takes an optional numeric argument to step multiple lines.

  • finish: Execute until current stack frame returns.

  • continue: Continue program execution and end the Pry session.

Installing ChromeDriver

ChromeDriver is a separate executable that Selenium WebDriver uses to control Chrome. We use ChromeDriver to run the integration tests in Foreman.

Installing plugins

In order to use a plugin, you’ll need to install its gem.

From source code:

cd foreman
echo "gem '<PLUGIN_NAME>', path: '../PLUGIN_PATH'" >> bundler.d/<PLUGIN_NAME>.local.rb

From github:

cd foreman
echo "gem '<PLUGIN_NAME>', git: 'https://github.com/theforeman/<PLUGIN_NAME>.git'" >> bundler.d/<PLUGIN_NAME>.local.rb

Then run bundle install from foreman to install the plugin and its dependencies. In case there are node modules dependencies that don’t exist in foreman, you will need to install them in the plugin via npm install. Another option is to re-run npm install in foreman, which will trigger in the end a postinstall script that will install all node modules of plugins.

After you’ve installed the dependencies, run bundle exec rake db:migrate and bundle exec rake db:seed to update the database scheme.

Running tests in plugins

Make sure to run plugins tests from the Foreman directory. In order to run rubocop test in the plugin, use the following command:

bundle exec rake <PLUGIN_NAME>:rubocop

To run all of the plugin’s tests:

npm install # make sure to install npm dependencies for webpack
bundle exec rake webpack:compile # only needed if you have integration tests that uses JS
bundle exec rake test:<PLUGIN_NAME>

To run a specific plugin’s test:

bundle exec rake test TEST="../<PLUGIN_PATH>/test/PATH/TO/TEST"

Forklift

Forklift provides tools to create Foreman+Katello environments for development, testing, and production configurations. Follow the installation guide.