New Developer Setup

Requirements Summary

Prerequisites

System packages

1. In order to compile Ruby, install the header files for OpenSSL, readline and zlib.

   dnf	sudo dnf -y install openssl-devel readline-devel zlib-devel
   yum	sudo yum -y install openssl-devel readline-devel zlib-devel
   apt	sudo apt -y install libssl-dev libreadline-dev zlib1g-dev
   brew	brew install openssl

2. In addition, in order to compile Ruby, native Gems and native NodeJS modules, other libraries are required.

   dnf	sudo dnf -y install @c-development libffi-devel postgresql-devel libxml2-devel libcurl-devel cmake python libssh2-devel
   yum	sudo yum -y install @development libffi-devel postgresql-devel libxml2-devel libcurl-devel cmake python libssh2-devel
   apt	sudo apt -y install build-essential libffi-dev libpq-dev libxml2-dev libcurl4-openssl-dev cmake python libssh2-1-dev
   brew	brew install cmake libssh2

   Note: Users with MacOS running on Apple M1 CPU might need to specify location of the Homebrew libraries explicitly. If build steps below fail for you then run export LIBRARY_PATH="$LIBRARY_PATH:$(brew --prefix)/lib"and retry the failing build step. See here for additional information: https://github.com/Homebrew/brew/issues/13481

Services

ManageIQ requires a memcached instance for session caching and a PostgreSQL database for persistent data storage.

memcached

1. Install

   dnf	sudo dnf -y install memcached
   yum	sudo yum -y install memcached
   apt	sudo apt -y install memcached
   brew	brew install memcached
   containers	N/A

2. Start the service

   systemd	systemctl enable --now memcached
   brew	brew services start memcached
   containers	podman run --detach --publish 11211:11211 memcached

PostgreSQL

1. Install

   dnf	sudo dnf -y install postgresql-server
   yum	sudo yum -y install postgresql-server
   apt	sudo apt -y install postgresql
   brew	brew install postgresql@13
   containers	N/A

2. Configure and start the cluster

   • Fedora / CentOS

     sudo PGSETUP_INITDB_OPTIONS='--auth trust --username root --encoding UTF-8' postgresql-setup --initdb
     

   • Debian / Ubuntu

     pg_version=$(pg_lsclusters --no-header | awk '{print $1}' | sort -n | tail -1)
     sudo pg_dropcluster --stop $pg_version main
     sudo pg_createcluster -e UTF-8 -l C $pg_version main -- --auth trust --username root
     sudo pg_ctlcluster $pg_version main start
     

   • macOS

     brew will configure the cluster automatically, but you will need to create the user.

     brew services start postgresql@13
     psql -c "CREATE USER root SUPERUSER PASSWORD 'smartvm';" -U $USER -d template1
     

     If not using brew, you can configure a cluster using initdb directly.

     rm -rf /usr/local/var/postgres
     initdb --auth trust --username root --encoding UTF-8 /usr/local/var/postgres
     

   • containers

     Skip ahead to “Start the service”

3. Start the service

   systemd	systemctl enable --now postgresql
   brew	Already started above
   containers	podman run --detach --publish 5432:5432 --env POSTGRES_USER=root postgres

Kafka

1. Install

   dnf	sudo dnf -y install kafka
   yum	sudo yum -y install kafka
   apt	sudo apt -y install kafka
   brew	brew install java kafka
   containers	N/A

2. Configure the service

   • macOS

     • Configure system to use Java

       sudo ln -sfn $(brew --prefix)/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
       

     • Configure KRaft (optional, if not using zookeeper)

       mv $(brew --prefix)/etc/kafka/server.properties $(brew --prefix)/etc/kafka/server.properties-zookeeper
       ln -s $(brew --prefix)/etc/kafka/kraft/server.properties $(brew --prefix)/etc/kafka/
       
       kafka-storage format -t $(kafka-storage random-uuid) -c $(brew --prefix)/etc/kafka/server.properties
       

3. Start the service

   systemd	systemctl enable --now kafka
   brew	brew services start kafka, brew services start zookeeper

nvm and JavaScript build utilities

nvm is strongly recommended for NodeJS version management.

nvm install 18
nvm use 18

# Set version 18 as the default for all scripts
nvm alias default 18

You may need to restart your shell in order to source the nvm initialization environment.

Then install yarn - you can find the recommended way for your platform at https://classic.yarnpkg.com/en/docs/install, or, if that fails, via npm.

npm install --global yarn

Ruby and Bundler

A Ruby version manager is strongly recommended. Use any one of the following:

• chruby + ruby-install
• rbenv + ruby-build
• rvm

Using the Ruby version manager, install Ruby and the latest bundler (as listed in the Requirements Summary above).

Clone ManageIQ

You must first fork the repository, clone it and then create an upstream remote. Additionally, to run the following commands you will need to setup an SSH key. Detailed instructions on how to do (as well as set up the recommended git and GitHub options) can be found in Git workflow.

git clone git@github.com:<username>/manageiq.git
cd manageiq
git remote add upstream git@github.com:ManageIQ/manageiq.git
git fetch upstream

Configure ManageIQ

A setup script is available to quickly set up the application. This script installs the required Gems, sets up necessary JavaScript libraries, creates and migrates the database, and finally seeds the database with initial content.

bin/setup

NOTE

• macOS requires platform specific Gems. Run bundle config specific_platform true before running bin/setup.

• The ovirt-engine-sdk gem contains C code that generated warnings with older Clang versions. These warnings are marked as errors in newer Clang 15 and 16 depending on the Clang version, architecture, and possibly OS. If this is the case, you can mark these as warnings and not errors to allow installation:

  gem install ovirt-engine-sdk -- --with-cflags="-Wno-error=incompatible-function-pointer-types -Wno-error=implicit-function-declaration"
  

  This can also be configured within bundler:

  bundle config build.ovirt-engine-sdk "--with-cflags=-Wno-error=incompatible-function-pointer-types\\ -Wno-error=implicit-function-declaration"
  

  See https://github.com/oVirt/ovirt-engine-sdk-ruby/issues/14 and https://github.com/oVirt/ovirt-engine-sdk-ruby/issues/11. Hopefully, the code in the gem can be resolved to avoid these warnings in the future.

• If you’ve run PostgreSQL in a container, be sure to export the DATABASE_URL variable to connect to the container over TCP instead of a UNIX file socket.

  export DATABASE_URL='postgresql://localhost:5432' # optional, only necessary if PostgreSQL is running in a container
  

Start ManageIQ

bundle exec rails server

The web UI should now be available at http://localhost:3000. The default username is admin and the default password is smartvm. If you can login, then everything is working! Press Ctrl-C to stop the Rails server.

ManageIQ runs a lot of work asynchronously via background queue workers, to simulate this we recommend running:

bundle exec rails console
simulate_queue_worker

Further Reading

• Individual workers can be started using Foreman directly.
• Running the test suites
• Seeding inventory data from provider tests
• Provider, UI and plugin development describes the plugin and external provider development process.
• ManageIQ Bot a bot to automate various developer problems such as commit monitoring, Github pull request and Travis monitoring.