Foreman: Open-Source Server Lifecycle Automation for On-Premises and Cloud Infrastructure

What Foreman Manages and Who Runs It

Foreman covers the full operational lifecycle of a server: discovery and provisioning of bare-metal hardware, deployment to private and public clouds, ongoing configuration management through external tools, and decommissioning. The README describes its intended audience as operations teams managing from tens to tens of thousands of servers. It is deployed in distributions such as RDO and RHOS (Red Hat OpenStack distribution), which indicates that large infrastructure environments are its primary use case.

The project's scope is explicitly broad. Rather than handling one part of the lifecycle, Foreman acts as the coordination layer above existing configuration management tools. An organization using Puppet to enforce system state can use Foreman to provision the machines that Puppet then manages, track the history of changes, and manage group policies from a central interface. The same applies to Ansible, Chef, and Salt, each of which integrates through a dedicated Foreman plugin.

Foreman is not a replacement for Ansible or Puppet. It does not execute configuration management tasks directly. Instead, it calls into whichever tools your environment already uses, adding provisioning, inventory, and lifecycle tracking on top.

Smart Proxy Architecture and Configuration Management Integration

The smart proxy is the component that allows Foreman to reach into remote network segments or data centers without requiring direct network access from the Foreman web server. Each smart proxy runs on or near the managed infrastructure and exposes a local API that Foreman calls. It handles tasks such as DHCP, DNS, TFTP for PXE booting, and serving Puppet or Ansible configuration to nearby hosts.

This architecture means that a single Foreman instance can manage geographically distributed infrastructure by deploying one smart proxy per site. Each proxy registers with the central Foreman server and reports host information back. The proxy layer also isolates the Foreman application from the configuration management tools: Foreman communicates with Puppet, Ansible, Chef, and Salt through the proxy interface rather than through direct API calls.

The README notes that LDAP authentication and role-based access control (RBAC) are built in. This makes Foreman suitable for organizations where multiple teams share infrastructure but require scoped access, such as a network team that can see network configuration but cannot modify system packages, or a development team that can provision hosts in a test environment but not in production.

Setting Up Foreman with Docker Compose

The repository includes a docker-compose.yml that brings up the full Foreman stack: a PostgreSQL database, the Foreman application server, a Sidekiq-based orchestrator, a worker, and two Redis instances. The application container is built from the official image and started as a Rails server:

image: quay.io/foreman/foreman:develop
command: bundle exec bin/rails server -b 0.0.0.0
environment:
  - DATABASE_URL=postgres://foreman:foreman@db/foreman?pool=5
  - RAILS_ENV=production
  - FOREMAN_FQDN=foreman.example.com
  - FOREMAN_DOMAIN=example.com

The `FOREMAN_FQDN` and `FOREMAN_DOMAIN` environment variables set the hostname that Foreman advertises to managed hosts. The application binds to port 3000 by default in this configuration.

For production installations, the README points to the official quickstart guide at theforeman.org/manuals/latest/quickstart_guide.html and the installation scenarios section for setups with specific requirements such as RHEL, Debian, or Ubuntu. The Docker path is not the recommended route for production; the installer packages are the supported path for production deployments according to the project documentation.

Web Frontend, CLI, and REST API Access

Foreman exposes three access surfaces. The web frontend provides a visual interface for all lifecycle operations: creating host groups, viewing provisioning history, managing users and roles, and monitoring infrastructure state. The README describes it as the primary interaction surface for day-to-day operations.

The CLI, referenced in the manual at theforeman.org/manuals/latest/index.html#4.5CommandLineInterface, provides scriptable access to the same operations available in the web UI. This makes it possible to integrate Foreman into deployment pipelines where provisioning a new host needs to happen programmatically.

The REST API is documented using apipie-rails and is available at /apidoc on any running Foreman instance. The API exposes all Foreman resources and allows external tools to query or modify inventory, trigger provisioning, or read audit logs. The API documentation is also published on the project website at theforeman.org/api/.

The package.json in the repository specifies that the frontend requires Node.js 22 and uses PatternFly 5 as its component library. The frontend is compiled at build time using webpack; the resulting assets are served as static files by the Rails application.

Extending Foreman with Plugins

Foreman's plugin system is based on Rails engines packaged as Ruby gems. A plugin adds new menu items, models, API endpoints, and UI tabs to the base application by declaring itself in the Gemfile and registering with Foreman's plugin hooks at load time.

The project wiki lists available plugins at projects.theforeman.org/projects/foreman/wiki/List_of_Plugins. Significant ones include foreman_ansible for Ansible integration, foreman_chef for Chef integration, and Katello for content lifecycle management (repository mirroring, subscription management, errata tracking). Katello is a particularly common addition in Red Hat environments because it provides the content management layer that sits between Foreman and a fleet of RHEL or CentOS hosts.

The README notes that plugins are easy to install but that adding and removing them is not always reversible without a database migration. Plugins that add database tables require running migrations on install; removing a plugin that added tables requires running down-migrations to avoid schema pollution.

Limitations and Cases Where Foreman Is the Wrong Choice

Foreman's operational complexity is its main limitation. Running it in production means maintaining a Rails application, a PostgreSQL database, Redis for task queuing, and one or more smart proxies. Teams that do not already have Rails operational experience will find the upgrade and debugging surface substantial.

Foreman is also not the right tool for simple task automation. If the goal is to run a playbook against a list of hosts on demand, Ansible AWX covers that case with a lighter footprint and without the provisioning and inventory overhead that Foreman carries. Foreman adds value when provisioning new machines is a regular operational task and when inventory tracking across the full lifecycle is a requirement.

The README does not document rollback procedures for failed provisioning jobs. When a host fails to build, the README does not document the recovery path, which means teams must develop their own runbooks for failure handling before relying on Foreman in a production environment.

Foreman vs. Ansible AWX

Ansible AWX is the open-source upstream of Red Hat Ansible Automation Platform and is the closest commonly used alternative for teams that primarily use Ansible. AWX focuses on running Ansible playbooks and managing inventories through a web interface, with role-based access control and job scheduling.

The key difference is scope. Foreman covers the full server lifecycle including bare-metal provisioning via PXE, DHCP, and DNS management, whereas AWX assumes that the machines already exist and are accessible. Foreman also integrates with multiple configuration management systems, not just Ansible. AWX is the better fit for teams whose infrastructure is entirely cloud-based or virtualized and who only need Ansible workflow management. Foreman is the better fit for teams that provision physical hardware or need a single control plane across Puppet and Ansible environments.

The Foreman plugin for Ansible (foreman_ansible) adds Ansible integration to an existing Foreman installation, so it is also possible to use both tools together, with Foreman handling provisioning and AWX handling playbook orchestration.

Maintenance Status and GPL-3 License Implications

The last push to this repository was on September 25, 2026, three days before publication. The repository is under active development with continuous commits.

The core Foreman repository is licensed under the GNU GPL v3 or newer, with some exceptions documented in the LICENSE file. The README states that the repository is free software that can be redistributed and modified under GPL-3 terms, with copyright held by Ohad Levy, Paul Kelly, and their respective owners from 2009 onward.

The GPL-3 license has a consequence for organizations building internal tools on top of Foreman: any modifications to the Foreman codebase that are distributed externally must be released under GPL-3. Internal use does not trigger distribution requirements, but distributing a modified Foreman instance to customers does. The license of individual plugins can differ from GPL-3; plugin authors set their own licenses, which means a closed-source plugin is possible but must be checked for compatibility with the core license.

Editorial conclusion

Foreman suits operations teams that already run one of the supported configuration management systems and need a single web-accessible control plane for provisioning, inventory, and history. It is the wrong choice for teams that want a lightweight task runner or that do not need bare-metal provisioning. Before adopting it, verify that your chosen configuration management tool has an active Foreman plugin, that your team can manage a Rails application in production, and that the GPL-3 license is compatible with any closed-source plugins your workflow requires.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. theforeman/foreman on GitHub