I’ve had a few requests to do a write up of a Forklift workflow for development environments. While there are a few different ways to build a development environment, the forklift tool provides an isolated environment through Vagrant and allows for easy replication of environments with some customization. Forklift can also be used to spin up various flavors of production environments but for this post I am going to focus on development.
As part of writing this post, I went through these steps fresh myself so if you hit any errors please reply here and we’ll work through them.
Forklift uses Vagrant to spin up virtual machines and configure an environment. Provisioning is handled by Ansible playbooks.
For the purposes of this, I will be assuming the use of a yum based host such as Fedora or CentOS with libvirt. The use of Virtualbox for those on a Mac is possible but largely untested. Ensure that you have the latest Vagrant and Ansible installed.
sudo yum -y install ansible libvirt-daemon-kvm sudo yum -y local-install https://releases.hashicorp.com/vagrant/2.0.2/vagrant_2.0.2_x86_64.rpm sudo chkconfig libvirtd on
Now clone the Forklift repository:
git clone https://github.com/theforeman/forklift cd forklift
There are a number of boxes (i.e. virtual machine configurations) that come batteries included with Forklift that can be viewed by doing an initial
vagrant status. The definitions for boxes can be found in the
boxes.d/ folder. The one we are interested in for development is
boxes.d/99-local.yaml.example. Let’s copy that from being an example to a real box file:
cp boxes.d/99-local.yaml.example boxes.d/99-local.yaml
This copy of the file is not checked into git so we can modify it without worry of committing changes. Within this copied box file we are interested in the primary development box definition:
centos7-devel: primary: true box: centos7 ansible: playbook: 'playbooks/devel.yml' group: 'devel' variables: ssh_forward_agent: true foreman_devel_github_push_ssh: True katello_devel_github_username: <REPLACE ME>
Now we are ready to spin up the development box (this takes around 20 minutes to run):
vagrant up centos7-devel
Post Install Activities
The development environment at present lacks complete NPM support and is in progress. Until that time users need to do the following:
sudo yum -y install npm cd foreman/ npm install cat > .env <<EOF BIND=0.0.0.0 PORT=3000 EOF
This is needed due to the standard Rails 5+ port of 5000 is used by Pulp’s crane service. There is also an HTTPS reverse proxy running that looks for 3000.
At this point there are two options:
- use the built in webpack devserver (recommended for those modifying UI code)
- precompile webpack to a faster environment (recommend for those not modifying UI code)
Built in Webpack Server
foreman/config/settings.yaml and set
Now start the server:
This option precompiles the webpack bundle and will need to be re-run anytime you make UI changes.
Now start the server:
Accessing the Dev Server
The development server can now be accessed via http://<ip_of_virtual_machine:3000 and, when precompiling webpack, over HTTPS at
What’s On the Box
After the installation completes, the development environment is configured with the following:
- foreman and katello git checkout in /home/vagrant/
- Foreman proxy running in the background on port 9090
- Postgres with initial database created and migrated
- Pulp and MongoDB running in the background
- Candlepin running under tomcat in the background
- Puppetserver running in the background
- Apache running for Pulp and with an HTTPS reverse proxy pointing to the standard Rails development port (3000)
- Pulp crane running on port 5000
Code via NFS
Code can be mounted over NFS to the Vagrant VM to use your favorite editor such as Rubymine when making changes. Please refer to the README for more information or ask in #theforemandev as a number of developers use this technique.
Adding Additional Foreman Plugins
If you’d like to have more than the base level Foreman and Katello checked out via git, then can be added to the box definition:
variables: foreman_installer_options: " --katello-devel-extra-plugins theforeman/foreman_remote_execution --katello-devel-extra-plugins theforeman/foreman_discovery "
Things like box memory and cpus can be increased by setting it on the box definition. For a comprehensive list of options see here.
If you run into issues with the initial setup or using NFS mounts please see our Troubleshooting doc first. We are happy to help with any issues either here or via Github issues on the repository.
There are a few steps that are manual in this process that are candidates for being added baseline to the development setup or are in progress. If you run into issues or have feature requests feel free to file a Github issue. Contributions are always welcome to enhance the setup for different user configurations.