Table of Contents
This page intends to describe the steps required to run a quick and successful installation of Foreman including a migration to MySQL as backend. At the end of the procedure you should have an instance available containing a foreman-proxy, a web gui, a working puppet master, and either a PostgreSQL or MySQL backend, depending on your choice.
Especially when you are about to build your own brand new puppet environment to automate your infrastructure, this is a great starting point to have a working, scalable environment up and running, ready for code deployment within less then half an hour!
Another great use case would be if you happen to consider an 'upgrade' of your current environment. Puppet and Foreman are ruby-based, and upgrading the package base very often easily breaks everything especially with Foreman. Also, new puppet versions do bring in syntax changes, which may or may not be breaking your infrastructre. So insteadof direct upgrades, you may want to build a new instance of Puppet and Foreman altogether, test your modules with it and if all is good, either replace the old environment or simply point your infrastructure to the new environment, leaving you the possibility to fall back.
Expected installation time (excluding OS & database provision if desired): 15 minutes.
Warning: This walk-through assumes a fresh vanilla install, at the very least no httpd installation to be in place. The Foreman installer WILL overwrite the configuration with a Passenger configuration!
Do not apply this to an existing web server running httpd / apache, without backing up your configuration files first!!
What is Foreman
"Foreman is a complete lifecycle management tool for physical and virtual servers". "Foreman is an open source project that gives system administrators the power to easily automate repetitive tasks, quickly deploy applications, and proactively manage servers, on-premises or in the cloud." These are comments taken right from the Foreman website.
Foreman integrates very well with Puppet, an excellent tool for automated configuration management. While Puppet can be used with its own web console, the far better choice is to use Foreman instead. It gives you much more details about your hosts, allows reporting, trending, direct management of your hosts, and performs & scales way better then the Puppet web console.
Whether you need to fully provision your server infrastructure, or just require reporting and occasional server management, Foreman is a great choice. The setup via Apache Passenger used to be tricky and time consuming, but is now done within minutes via Puppet (the Foreman installer utilizes Puppet do that).
System requirements and supported platforms are listed here.
- Foreman in a virtual machine works very well and is recommended.
- 512 MB of RAM is required minimum. If you run out of memory during the installation process (Ruby can be memory-hungry), just add a SWAP file on the fly, which gives you more memory as needed. Once the installation is finished, this amount of memory is well enough to run Foreman and Puppet master. For larger environments, you can add memory when required. However if you manage many hosts, you will need to add more memory.
- OS of choice: CentOS 6 . This article assumes an already installed OS (minimal version is sufficient and recommended).
- EPEL repository must be available.
- Required firewall rules are listed here. Note that most of those ports are actually for services other than Foreman, i.e. DNS, DHCP, Apache etc. If you plan to use all features of Foreman, you will need all those ports open. It is highly recommended to configure your firewall before the installation, or disable it for the time being.
As mentioned before, this assumes a 'vanilla' installation (i.e. just the OS itself), and only doing the steps below.
Update the OS
$ sudo yum update
$ sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum -y install http://yum.theforeman.org/releases/latest/el7/x86_64/foreman-release.rpm
$ sudo yum -y install
import GPG key for SCL
$ sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo
install additional packages:
$ sudo yum install -y foreman-cli foreman-console foreman-selinux foreman-mysql2
or in case you want all available packages:
$sudo yum -y install foreman*
install Foreman installer
$ sudo yum -y install foreman-installer
Running the foreman-installer
The foreman-installer can be run as default installation, with specific parameters, or interactive.
Quickest and easiest way appears to be the default installation. The default will make use of postgresql and a few other things, is done like this:
$ sudo foreman-installer
Just watch the foreman installation do the hard work, takes probably 5-10 minutes. Once this is finished, you will see a success message on the console, the URLs for accessing Foreman and Foreman-proxy, as well as initial credentials are displayed and you should already able to access things (assuming firewall is open). If you do not plan to change databases (see below) , you are already done at this stage and can login to Foreman.
Running the Foreman configuration
The default installer makes use of a postgresql database, which does not have a graphical interface available for management.
Also, if you ever think of re-installing Foreman, the default database likely is to be overwritten. As such, changing this to MySQL is recommended. (This requires foreman-mysql2 to be installed, see above #installation_steps). In that case, you need to create an empty database manually before the next step. Using an external database server is highly recommended for performance reasons.
Once the database is created and accessible, the next thing is to change the settings in /etc/foreman/database.yml:
Should you make use of environments for 'development' and 'test', you can change those too. Per default these are sqlite databases. If you choose to change those too, every environment must have its own database. You cannot share them.
Afterwards, run 2 final rake tasks to populate the databases:
$ sudo foreman-rake db:migrate
$ sudo foreman-rake db:seed
The seeding process should include the initial login credentials, and display them at the console.
Finally, restart Foreman to start actually using the database. Cookies & browser cache might need clearing, if a connection had been established previously already.
You should be ready to login to Foreman now.
The interactive installation is done via a list of menu options, which you can individually change. This process might allow you to change settings right before the installation. But it almost certainly takes much longer to go through the options, and the result still might not be what you had intended.
To run an interactive installation, execute
$ sudo foreman-installer -i
Help & Instructions
If you choose to poke around and try other ways, you can always display the available parameters via foreman-installer --help and then executed as required,