{"id":13602096,"url":"https://github.com/theforeman/forklift","last_synced_at":"2025-05-15T20:05:09.237Z","repository":{"id":13458980,"uuid":"16148652","full_name":"theforeman/forklift","owner":"theforeman","description":"Helpful deployment scripts for Foreman and Katello","archived":false,"fork":false,"pushed_at":"2025-05-08T09:17:44.000Z","size":2415,"stargazers_count":186,"open_issues_count":62,"forks_count":199,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-05-08T10:28:20.425Z","etag":null,"topics":["ansible","foreman","forklift","hacktoberfest","katello","playbooks","vagrant"],"latest_commit_sha":null,"homepage":"https://theforeman.github.io/forklift","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theforeman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-22T18:44:49.000Z","updated_at":"2025-05-08T09:17:48.000Z","dependencies_parsed_at":"2024-11-06T13:33:24.729Z","dependency_job_id":null,"html_url":"https://github.com/theforeman/forklift","commit_stats":{"total_commits":1833,"total_committers":131,"mean_commits":"13.992366412213741","dds":0.7152209492635024,"last_synced_commit":"316b107700168d352f91d2e27e3785c09cadcfcc"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theforeman%2Fforklift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theforeman%2Fforklift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theforeman%2Fforklift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theforeman%2Fforklift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theforeman","download_url":"https://codeload.github.com/theforeman/forklift/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","foreman","forklift","hacktoberfest","katello","playbooks","vagrant"],"created_at":"2024-08-01T18:01:14.018Z","updated_at":"2025-05-15T20:05:03.683Z","avatar_url":"https://github.com/theforeman.png","language":"Shell","funding_links":[],"categories":["Shell","vagrant","ansible"],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/theforeman/forklift/master/docs/forklift.png\" height=\"100px\"\u003e\n\n# Forklift: lifting Foreman into your environment\n\nForklift provides tools to create Foreman/Katello environments for development, testing and production configurations. Whether you are a developer wanting an environment to write code, or a user wanting to spin up the latest production environment for deployment or evaluation Forklift has you covered.\n\n * [Using Forklift](#using-forklift)\n   - [Requirements](#requirements)\n   - [Quickstart](#quickstart)\n   - [Foreman Nightly Box](#foreman-nightly-box)\n   - [Katello Nightly Box](#katello-nightly-box)\n   - [Additional Documentation](#additional-documentation)\n   - [Development Environment](#development-environment)\n   - [Using Playbooks and Roles Without Vagrant](#using-playbooks-and-roles-without-vagrant)\n   - [Credentials](#credentials)\n   - [Poor man's DNS a.k.a /etc/hosts](#poor-mans-dns-aka-etchosts)\n   - [Adding Custom Boxes](#adding-custom-boxes)\n   - [Using SSHFS to share folders](#using-sshfs-to-share-folders)\n   - [Using NFS to share folders](#using-nfs-to-share-folders)\n   - [Customize Deployment Settings](#customize-deployment-settings)\n   - [Customize Available Boxes](#customize-available-boxes)\n   - [Post Install Playbooks](#post-install-playbooks)\n   - [Using Local Ansible Collection](#using-local-ansible-collection)\n * [Production Environments](https://theforeman.github.io/forklift/production/)\n * [Development Environments](https://theforeman.github.io/forklift/development/)\n * [Stable Boxes](https://theforeman.github.io/forklift/stable_boxes/)\n * [Testing Environments](https://theforeman.github.io/forklift/testing/)\n * [Provisioning environment](https://theforeman.github.io/forklift/provision/)\n * [Plugins](https://theforeman.github.io/forklift/plugins/)\n * [Using Forklift as a Library](https://theforeman.github.io/forklift/library/)\n * [Troubleshooting](https://theforeman.github.io/forklift/troubleshooting/)\n * [Vagrant](https://theforeman.github.io/forklift/vagrant/)\n * [Packer](https://theforeman.github.io/forklift/packer/)\n\n## Using Forklift\n\n### Requirements\n\n* Vagrant - 2.2+ - Both the VirtualBox and Libvirt providers are tested\n* Ansible - 2.12+\n* [Vagrant Libvirt provider plugin](https://github.com/vagrant-libvirt/vagrant-libvirt) (if using Libvirt)\n* Virtualization enabled in BIOS\n\nSee [Installing Vagrant](docs/vagrant.md) for installation instructions.\n\n### Quickstart\n\nThe quickstart guide covers the basic steps to install Forklift so that you can quickly spin up a production test environment of the latest bleeding edge nightly Foreman or Katello build.\n\nIt assumes you have already Vagrant and libvirt installed, as well as the vagrant-libvirt and vagrant-hostmanager plugins. You also need Ansible, although if you don't have it or aren't sure if your version is compatible, you can simply create and activate a Python virtual environment and then `pip install ansible-galaxy`\n\nStart by cloning the Forklift repository:\n\n```sh\ngit clone https://github.com/theforeman/forklift.git\ncd forklift\n```\n\nThen install the Ansible collections which are needed by Forklift:\n\n```sh\nansible-galaxy collection install -r requirements.yml\n```\n\nWhen this is complete, simply follow the next section of this README to try out the latest nightly Foreman build using Forklift.\n\n### Foreman Nightly Box\n\nSpin up your box and start using the latest nightly build of Foreman:\n\n```sh\nvagrant up centos9-stream-foreman-nightly\n```\n\nAccess the CLI by first connecting to the box via SSH:\n\n```sh\nvagrant ssh centos9-stream-foreman-nightly\n```\n\nTo access the WebUI, it's helpful to have the vagrant-hostmanager plugin installed, so that your Workstation will automatically be able to resolve the hostname of the box to its IP address.\n\nThen you can simply open your browser and navigate to `https://centos9-stream-foreman-nightly.\u003cHOSTNAME\u003e.example.com` where `\u003cHOSTNAME\u003e` is replaced by the shortname of your workstation. The first time you do this you will need to accept the self-signed certicate.\n\nBy default, `forklift` deploys Foreman with `admin`/`changeme` as username and password.\n\n### Katello Nightly Box\n\nKatello nightly boxes are available as well; simply change `centos9-stream-foreman-nightly` to `centos9-stream-katello-nightly` and the steps are otherwise exactly the same as above.\n\n### Additional Documentation\n\nThe remainder of this README contains helpful notes on additional topics that are likely to be of interest to users. For the most thorough and complete guides however, please refer to the [docs page](https://theforeman.github.io/forklift).\n\n### Katello Development Environment\n\nIf you want a Katello development environment, substitute your GitHub username for `GITHUB_NICK` and run:\n\n```sh\ncp vagrant/boxes.d/99-local.yaml{.example,}\nsed -i \"s/\u003cREPLACE ME\u003e/GITHUB_NICK/g\" vagrant/boxes.d/99-local.yaml\n```\n\nBring up the Katello Development Box:\n\n```sh\nvagrant up centos9-katello-devel\n```\n\nOnce the box is running, you can access the shell via SSH and modify the source code in the `~/foreman` and `~/katello` directories. Then start the application to preview your changes:\n\n```sh\ncd ~/foreman\nbundle exec foreman start\n```\n\nBefore you can access the WebUI, you must first accept the self-signed certificate on port 3808 by visiting `https://centos9-katello-devel.\u003cHOSTNAME\u003e.example.com:3808` in your browser.\n\nThen, navigate to `https://centos9-katello-devel.\u003cHOSTNAME\u003e.example.com/` to access the WebUI and preview your changes.\n\nAs above, `\u003cHOSTNAME\u003e` refers to the shortname of your hypervisor.\n\nThere is a much more detailed guide to the development environments in the [full documentation](https://theforeman.github.io/forklift/development/).\n\nSee the developer documentation within the Foreman and Katello repositories for instructions on running the test suites, submitting pull requests, etc.\n\n### Using Playbooks and Roles without Vagrant\n\nIn case using Vagrant is not desired, ansible playbooks and roles from this repo can be used separately. This is useful if an existing host should be used for the installation, e.g. a beaker machine. In order to deploy the devel environment on host test.example.com, the following needs to be done:\n\non test.example.com machine, where the dev env should be deployed\n```sh\nuseradd vagrant\necho \"vagrant\tALL=(ALL)\tNOPASSWD: ALL\" \u003e\u003e /etc/sudoers.d/vagrant\n```\n\nin forklift checkout\n```sh\necho -e \"[devel]\\ntest.example.com\" \u003e inventories/local_inventory\nansible-playbook --private-key=~/.ssh/id_rsa --user root --inventory inventories/local_inventory --extra-vars katello_devel_github_username=katello playbooks/devel.yml\n```\n\nIn an example above, ansible was instructed to use specific private key (overriding the value from ansible.cfg), root user was set as ssh user and playbook variable was set, so that checkout will be made from katello user.\n\nOther playbooks from playbooks/ directory can be used similarly, though some might need more variables and investigating their parameters is recommended first.\n\n### Credentials\n\nBy default `forklift` deploys Foreman with `admin`/`changeme` as username and password, please change this on production installs (either after the install, or by setting `foreman_installer_admin_password` during the initial deployment).\n\n### Poor man's DNS a.k.a /etc/hosts\n\nFor the multi-host setup, one of the easiest way of making the name\nresolution working with vagrant is using\n[vagrant-hostmanager](https://github.com/devopsgroup-io/vagrant-hostmanager). Forklift supports\nthis plugin by default. The only thing one needs to do is install the vagrant-hostmanager plugin:\n\n```sh\nvagrant plugin install vagrant-hostmanager\n```\n\nBy default, the boxes are set with `example.com` domain.\n\nIf you're using NetworkManager, [this advanced DNS configuration](https://m0dlx.com/blog/Automatic_DNS_updates_from_libvirt_guests.html)\nallows completely automated dns resolution using dnsmasq from host to guest and guest to guest.\n\nYou can disable hostmanager in `vagrant/settings.yaml` by setting `hostmanager_enabled` option.\n\nWhen using a briged network or with multiple network interfaces, the hostmanager would resolve the internal ip from the ssh-info, you can choose an ip of a particular network interface in `vagrant/settings.yaml` by setting `hostmanager_ip_resolver_device` option with the device name.\n\n```yaml\nhostmanager_ip_resolver_device: 'eth1'\n```\n\n### Adding Custom Boxes\n\nSometimes you want to spin up the same box type (e.g. centos9-katello-devel) from within the forklift directory. While this can be added to the Vagrantfile directly, updates to the forklift repository could wipe out your local changes. To help with this, you can define a custom box re-using the configuration within the Vagrantfile. To do so, create a `99-local.yaml` file in vagrant/boxes.d/. For example, to create a custom box on CentOS 9 Stream with nightly and run the installers reset command:\n\n```yaml\nmy-nightly-staging:\n  box: centos9-stream\n  ansible:\n    playbook: playbooks/katello.yml\n    variables:\n      katello_repositories_environment: staging\n    verbose: vvv\n```\n\nOptions:\n\n| Option                   | Description                                                           |\n|:-------------------------|:----------------------------------------------------------------------|\n| box                      |  the ':name' one of the defined boxes in the Vagrantfile |\n| bridged                  |  deploy on Libvirt with a bridged networking configuration, value of this parameter should be the interface of the host (e.g. em1) |\n| memory                   |  set the amount of memory (in megabytes) this box will consume |\n| cpus                     |  set the number of cpus this box will use |\n| hostname                 |  hostname to set on the box |\n| networks                 |  custom networks to use in addition to the management network |\n| disk_size                |  specify the size (in gigabytes) of the box's virtual disk. This only sets the virtual disk size, so you will still need to resize partitions and filesystems manually. |\n| add_disks                |  (libvirt provider only) specify additional libvirt volumes |\n| ansible                  |  updates the Ansible provisioner configuration including the playbook to be ran or any variables to set |\n| libvirt_options          |  sets Libvirt specific options, see [`config.rb` from `vagrant-libvirt`](https://github.com/vagrant-libvirt/vagrant-libvirt/blob/master/lib/vagrant-libvirt/config.rb) for possible options |\n| virtualbox_options       |  sets VirtualBox specific options |\n| openstack_options        |  sets OpenStack specific options |\n| google_options           |  sets Google specific options |\n| docker_options           |  sets Docker specific options |\n| domain                   |  forklift uses short name of your host + 'example.com' as domain name for your boxes. You can use this option to override it. |\n| sshfs                    |  if you have vagrant-sshfs plugin, you can use sshfs to share folders between your host and guest. See an example below for details. |\n| nfs                      |  share folders between host and guest.  See an example below for details. |\n| autostart                |  set to true to automatically start when using 'vagrant up' |\n| primary                  |  set the machine to be the default target of vagrant commands such as 'vagrant ssh' |\n| libvirt_qemu_use_session |  Use qemu session instead of system |\n\nEntirely new boxes can be created that do not orginate from a box defined within the Vagrantfile. For example, if you had access to a RHEL Vagrant box:\n\n```yaml\nrhel7:\n  box_name: rhel7\n  shell: 'echo TEST'\n  pty: true\n  libvirt: http://example.org/vagrant/rhel-7.box\n```\n\nExample with custom networking, static IP on custom libvirt network:\n\n```yaml\nstatic:\n  box: centos9\n  hostname: mystatic.box.com\n  networks:\n    - type: 'private_network'\n      options:\n        ip: 192.168.150.3\n        libvirt__network_name: lab-private\n        libvirt__iface_name: vnet2\n```\n\nExample with custom libvirt management network:\n\n```yaml\nstatic:\n  box: centos9\n  hostname: mystatic.box.com\n  libvirt_options:\n    management_network_address: 172.23.99.0/24\n```\n\nExample with openstack provider:\nYou will need to install vagrant openstack provider. For more information click [here](https://github.com/ggiamarchi/vagrant-openstack-provider).\nDo not forget to set openstack API credentials.\nTo use openstack provider as default look [here](https://www.vagrantup.com/docs/providers/default.html).\n\n```yaml\nopenstack-centos9:\n  image_name: 'Centos9'\n  username: 'centos'  #root by default\n  hostname: 'john-doe'\n  openstack_flavor: 'm1.medium'\n  sync_type: 'disabled'\n```\n\n### Using SSHFS to share folders\n\nYou will need to install [vagrant-sshfs](https://github.com/dustymabe/vagrant-sshfs) plugin. Make sure your host actually has sshfs installed.\nExample with sshfs mounting folder from guest to host:\n\n```yaml\nwith-sshfs:\n  box: centos9-stream\n  sshfs:\n    host_path: '/some/host/path'\n    guest_path: '/some/guest/path'\n    reverse: True\n```\n\nIf you want to mount in the opposite direction, just change `reverse` to `False` or remove it entirely.\n\nAdditonal options may be specified with using `options`.\n\n```yaml\nwith-sshfs-options:\n  box: centos9-stream\n  sshfs:\n    host_path: '/some/host/path'\n    guest_path: '/some/guest/path'\n    options: '-o allow_other'\n```\n\nExample with an additional disk (libvirt volume) presented as /dev/vdb in the vm:\n\n```yaml\nstatic:\n  box: centos9-stream\n  hostname: mystatic.box.com\n  add_disks:\n    - size: 100GiB\n      device: vdb\n      type: qcow2\n```\n\n### Using NFS to share folders\n\nAn alternative to SSHFS is to share the folders with NFS.  It is slightly more work than SSHFS.  See the [Fedora developer documentation](https://developer.fedoraproject.org/tools/vagrant/vagrant-nfs.html) for information about how to configure an NFS server for Vagrant.\n\nThen create your box:\n\n```yaml\nwith-nfs:\n  box: centos9-stream\n  nfs:\n    host_path: '/some/host/path'\n    guest_path: '/some/guest/path'\n```\n\n### Customize Deployment Settings\n\n\nSome settings can be customized for the entirety of the deployment by copying `vagrant/settings.yaml.example` to `vagrant/settings.yaml` and add, remove or updating:\n\n * memory: Memory to give boxes by default unless specified by a box\n * cpus: Number of CPUs to give boxes by default unless specified by a box\n * scale_memory: Factor to multiply memory of boxes that specify an own value\n * scale_cpus: Factor to multiply CPUs of boxes that specify an own value\n * sync_type: type of sync to use for transfer to the Vagrant box\n * mount_options: options for the vagrant-cachier plugin\n * domain: domain for your hosts, you can override this per-box by configuring your box with a domain directly\n * libvirt_options, virtualbox_options, openstack_options, google_options: custom options for the various providers\n\n### Customize Available Boxes\n\nThe list of available boxes can be customized by setting an exclude list in `vagrant/settings.yaml`. This allows faster `vagrant status` calls as well as reducing the the scope of boxes a user sees to tailor to their use cases. To specify boxes to exclude add the following to `vagrant/settings.yaml`, for example, to remove fips, fedora and any Foreman 1.2X boxes from view:\n\n```yaml\nboxes:\n  exclude:\n    - \"katello\" # exclude any box containing \"katello\"\n    - \"ubuntu1804-foreman-2\\\\.0\" # exclude only the box \"ubuntu1804-foreman-2.0\". Notice the escaped '.' character to match the specific character instead of any single character\n    - \"^centos9\" # exclude any box that starts with \"centos9\"\n    - \"foreman-1\\\\.(?:[2][0-3])\" # exclude any foreman-1.20 to foreman-1.23 version box\n```\n\n### Post Install Playbooks\n\nBoxes can be further customized by declaring Ansible playbooks to be run during provisioning. One or more playbooks can be specified and will be executed sequentially. An ignored directory can be used to put playbooks into 'user_playbooks' without worrying about adding them during a git commit.\n\nAnsible roles may also be installed directly using the [`ansible-galaxy` command](http://docs.ansible.com/ansible/galaxy.html#the-ansible-galaxy-command-line-tool). These roles will be installed at `playbooks/galaxy_roles` and will be ignored by git. You may also specify roles in a `requirements.yml`, which you can use to install all desired roles with `ansible-galaxy install -r requirements.yml`\n\n```yaml\nansible:\n  box: centos9-stream-katello-nightly\n  ansible:\n    playbook:\n      - 'user_playbooks/vim.yml'\n      - 'user_playbooks/zsh.yml'\n```\n\n### Using Local Ansible Collection\n\nIf needing to use a local copy of an Ansible collection used by Forklift, such as developing updates to theforeman.operations collection, you can temporarily update the `requirements.yml` to point at your local checkout:\n\n```yaml\ncollections:\n  - name: git+file:///home/user/path/to/repo/.git\n    type: git\n```\n\nThen run `ansible-galaxy` install:\n\n```sh\nansible-galaxy collection install -r requirements.yml --force-with-deps\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheforeman%2Fforklift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheforeman%2Fforklift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheforeman%2Fforklift/lists"}