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.
This derives from the Forklift documentation that can be found in the development docs. Advanced configuration such as memory increasing or poor-man’s DNS can also be found in the README.
Forklift uses Vagrant to spin up virtual machines and configure an environment. Provisioning is handled by Ansible playbooks.
Dependencies
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
Setup Forklift
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>
The first step is to edit boxes.d/99-local.yaml and set your github username in place of <REPLACE_ME>. Note that this assumes that you have forked both the Foreman and Katello repositories.
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
Edit foreman/config/settings.yaml and set :webpack_dev_server: to true
Now start the server:
foreman start
Precompile Webpack
This option precompiles the webpack bundle and will need to be re-run anytime you make UI changes.
rake webpack:compile
Now start the server:
rails s
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 https://<ip_of_virtual_machine/
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
Advanced Topics
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
"
Customized Environments
Things like box memory and cpus can be increased by setting it on the box definition. For a comprehensive list of options see here.
Troubleshooting
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.
Notes
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.