Newer version available

This quickstart guide is for Foreman 1.10, but the latest version is 1.19.

Quickstart Guide

The Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup. It uses native OS packaging (e.g. RPM and .deb packages) and adds necessary configuration for the complete installation.

Components include the Foreman web UI, Smart Proxy, Passenger (for the puppet master and Foreman itself), and optionally TFTP, DNS and DHCP servers. It is configurable and the Puppet modules can be read or run in “no-op” mode to see what changes it will make.

Supported platforms

  • CentOS, Scientific Linux or Oracle Linux 6 or 7, x86_64
  • Debian 8 (Jessie), i386/amd64/armhf
  • Debian 7 (Wheezy), i386/amd64
  • Fedora 19, x86_64
  • Red Hat Enterprise Linux 6 or 7, x86_64
  • Ubuntu 14.04 (Trusty), i386/amd64/armhf
  • Ubuntu 12.04 (Precise), i386/amd64

Other operating systems will need to use alternative installation methods (see the manual).

Installation

The Foreman installer uses Puppet to install Foreman. This guide assumes that you have a newly installed operating system, on which the installer will setup Foreman, a Puppet master with Passenger and the Smart Proxy by default.

Select operating system

To provide specific installation instructions, please select your operating system:

Repositories

No operating system selected.

First, enable the RHEL Optional and RHSCL repos:

yum-config-manager --enable rhel-6-server-optional-rpms rhel-server-rhscl-6-rpms

Check the repositories are enabled with yum repolist after running the above command, as it can silently fail when subscription does not provide it. More information about accessing RH Software Collections (RHSCL) is available from the Customer Portal.

If you're using RH Satellite 5, you should instead sync and enable the channels there.

First, enable the RHEL Optional and RHSCL repos:

yum-config-manager --enable rhel-7-server-optional-rpms rhel-server-rhscl-7-rpms

Check the repositories are enabled with yum repolist after running the above command, as it can silently fail when subscription does not provide it. More information about accessing RH Software Collections (RHSCL) is available from the Customer Portal.

If you're using RH Satellite 5, you should instead sync and enable the channels there.

Foreman on Fedora 19 has some known issues, and we'd recommend using a different distro instead.

Using a recent version of Puppet is recommended, which is available from the Puppet Labs repository. You may skip this and use the older version from EPEL without a problem, however it has reduced community support.

yum -y install http://yum.puppetlabs.com/puppetlabs-release-el-6.noarch.rpm

Enable the EPEL (Extra Packages for Enterprise Linux) and the Foreman repos:

yum -y install http://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
yum -y install http://yum.theforeman.org/releases/1.10/el6/x86_64/foreman-release.rpm

Enable the EPEL (Extra Packages for Enterprise Linux) and the Foreman repos:

yum -y install epel-release http://yum.theforeman.org/releases/1.10/el6/x86_64/foreman-release.rpm

Using a recent version of Puppet is recommended, which is available from the Puppet Labs repository. You may skip this and use the older version from EPEL without a problem, however it has reduced community support.

yum -y install http://yum.puppetlabs.com/puppetlabs-release-el-7.noarch.rpm

Enable the EPEL (Extra Packages for Enterprise Linux) and the Foreman repos:

yum -y install http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install http://yum.theforeman.org/releases/1.10/el7/x86_64/foreman-release.rpm

Enable the EPEL (Extra Packages for Enterprise Linux) and the Foreman repos:

yum -y install http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install http://yum.theforeman.org/releases/1.10/el7/x86_64/foreman-release.rpm

You may optionally use the latest available version of Puppet from the Puppet Labs repositories, which is a bit newer than that provided by Fedora itself.

yum -y install http://yum.puppetlabs.com/puppetlabs-release-fedora-19.noarch.rpm

Enable the Foreman repo:

yum -y install http://yum.theforeman.org/releases/1.10/f19/x86_64/foreman-release.rpm

Note that Puppet Labs does not provide Puppet 3.x packages for jessie.

Enable the Foreman repo:

echo "deb http://deb.theforeman.org/ jessie 1.10" > /etc/apt/sources.list.d/foreman.list
echo "deb http://deb.theforeman.org/ plugins 1.10" >> /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -

Using a recent version of Puppet is recommended, which is available from the Puppet Labs repository. You may skip this and use the older version from Debian without a problem, however it has reduced community support.

apt-get -y install ca-certificates
wget https://apt.puppetlabs.com/puppetlabs-release-wheezy.deb
dpkg -i puppetlabs-release-wheezy.deb

Enable the Foreman repo:

echo "deb http://deb.theforeman.org/ wheezy 1.10" > /etc/apt/sources.list.d/foreman.list
echo "deb http://deb.theforeman.org/ plugins 1.10" >> /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -

Using a recent version of Puppet is recommended, which is available from the Puppet Labs repository. You may skip this and use the older version from Ubuntu without a problem, however it has reduced community support.

apt-get -y install ca-certificates
wget https://apt.puppetlabs.com/puppetlabs-release-precise.deb
dpkg -i puppetlabs-release-precise.deb

Enable the Foreman repo:

echo "deb http://deb.theforeman.org/ precise 1.10" > /etc/apt/sources.list.d/foreman.list
echo "deb http://deb.theforeman.org/ plugins 1.10" >> /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -

You may optionally use the latest available version of Puppet from the Puppet Labs repositories, which is a bit newer than that provided by Ubuntu itself.

apt-get -y install ca-certificates
wget https://apt.puppetlabs.com/puppetlabs-release-trusty.deb
dpkg -i puppetlabs-release-trusty.deb

Enable the Foreman repo:

echo "deb http://deb.theforeman.org/ trusty 1.10" > /etc/apt/sources.list.d/foreman.list
echo "deb http://deb.theforeman.org/ plugins 1.10" >> /etc/apt/sources.list.d/foreman.list
wget -q http://deb.theforeman.org/pubkey.gpg -O- | apt-key add -

Downloading the installer

No operating system selected.
yum -y install foreman-installer
apt-get update && apt-get -y install foreman-installer

Running the installer

Ensure that ping $(hostname -f) shows the real IP address, not 127.0.1.1. Change or remove this entry from /etc/hosts if present.

The installation run is non-interactive, but the configuration can be customized by supplying any of the options listed in foreman-installer --help, or by running foreman-installer -i for interactive mode. More examples are given in the Installation Options section. Adding -v will disable the progress bar and display all changes. To run the installer, execute:

foreman-installer

After it completes, the installer will print some details about where to find Foreman and the Smart Proxy and Puppet master if they were installed along Foreman. Output should be similar to this:

  * Foreman is running at https://theforeman.example.com
      Initial credentials are admin / 3ekw5xtyXCoXxS29
  * Foreman Proxy is running at https://theforeman.example.com:8443
  * Puppetmaster is running at port 8140
  The full log is at /var/log/foreman-installer/foreman-installer.log

More quickstart resources…

Continue reading the quickstart guide in the manual:

Or view the quickstart screencasts:

Additional reading…

Foreman 1.19.0 has been released! Follow the quick start to install it.

Foreman 1.18.3 has been released! Follow the quick start to install it.

Foreman 1.17.4 is now available with important bug fixes. Follow the quick start to install it.