Vagrant Options¶

Full configuration of Vagrant is outside the scope of our documentation, but there are some common options that might be useful to multiple developers. These tips are documented here, but are not "supported". This guide assumes familiarity with our official dev setup guide: http://docs.pulpproject.org/en/3.0/nightly/contributing/dev-setup/index.html

Keep a Vagrant box for Pulp 2 and Pulp 3¶

To quickly switch bewteen Pulp 2 and Pulp 3, the simplest solution is to keep a completely separate vm for each, which means that you need a full set of git repositories checked out to the correct branches for each .

1. Create a second set of repositories. Create a copy of the directory that contains all of your Pulp git repositories. The names is not important, but I will reference this example:

cp -r ~/devel ~/3dev
mv ~/devel ~/2dev

2. Align the git checkouts. You can use `checkout.py` or manually align the git branches.

3. Update your Vagrantfile.
"~/2dev/devel/Vagrantfile" picks up the changes in https://github.com/pulp/devel/blob/master/Vagrantfile.example
"~/3dev/devel/Vagrantfile" picks up the changes in https://github.com/pulp/devel/blob/3.0-dev/Vagrantfile.example

4. Playbooks tracked by git have been updated. If you use additional playbooks, you may need to update the `hosts` line.

5. Delete your old libvirt or docker machine using virt-manager

6. `vagrant destroy` and `vagrant up`

Vagrant providers:¶

There are two Vagrant providers available for use: ``libvirt`` (using a virtual machine) and``docker`` (using a `docker <https://www.docker.com/&gt;\`_ container).

libvirt:¶

Reasons to prefer libvirt:

• doesn't require disabling SELinux on host
• doesn't grant the development environment root-equivalent privileges on host
• may run a different kernel on host vs guest

Requirements:

• vagrant-libvirt

docker:¶

• uses less resources (RAM, CPU and disk)
• host may freely access processes within the guest (e.g. for debugging)

Requirements:

• docker

You will need to enable and start the docker service:

$ sudo systemctl enable docker
$ sudo systemctl start docker

Cache RPM Packages¶

You can configure your Vagrant enviroment to cache RPM packages you download with dnf. To do
this, uncomment the line ``'.dnf-cache' => '/var/cache/dnf'``, which syncs the ``.dnf-cache``
directory (relative to the Vagrantfile) to ``/var/cache/dnf``. You will need to create the
``.dnf-cache`` directory manually with ``mkdir .dnf-cache``.

Vagrant without sudo¶

When using Vagrant, you probably have noticed that you are frequently prompted for passwords to
manage libvirt. You can configure your system policy to allow your user to manage libvirt without
needing root privileges. Create ``/etc/polkit-1/localauthority/50-local.d/libvirt.pkla`` with the
following contents, substituting with your user id::

[Allow your_user_id_here libvirt management permissions]
Identity=unix-user:your_user_id_here
Action=org.libvirt.unix.manage
ResultAny=yes
ResultInactive=yes
ResultActive=yes

Speed improvements:¶

KVM unsafe cache¶

You can configure your Vagrant environment to use
`kvm's unsafe cache mode <http://libvirt.org/formatdomain.html#elementsDisks&gt;\`_. If you do this,
you will trade data integrity on your development environment's filesystem for a noticeable speed
boost. In your Vagrantfile, there is a commented line ``domain.volume_cache = "unsafe"``. To use
the unsafe cache mode, simply uncomment this line.

You can also configure Vagrant to use the unsafe cache for all Vagrant guests on your system by
creating ``~/.vagrant.d/Vagrantfile`` with the following contents::

1. * mode: ruby *
2. vi: set ft=ruby :
   Vagrant.configure(2) do |config|
   config.vm.provider :libvirt do |domain|
   # Configure the unsafe cache mode in which the host will ignore fsync requests from the
   # guest, speeding up disk I/O. Since our development environment is ephemeral, this is
   # OK. You can read about libvirt's cache modes here:
   # http://libvirt.org/formatdomain.html#elementsDisks
   domain.volume_cache = "unsafe"
   end
   end
   .. warning::
   This is dangerous! However, the development environment is intended to be "throw away", so
   if you end up with a corrupted environment you will need to destroy and recreate it.
   Fortunately, the code you are working on will be shared from your host via NFS so your work
   should have data safety.

Vagrant with PyCharm¶

PyCharm 5.0.1 is mostly usable with Vagrant.

Remote Debugging¶

To use a remote debugger provided by PyCharm, ensure the PyCharm debug egg is installed in the
Vagrant environment. This can be done in the Vagrant environment using ``sudo pip``
so it is available in all virtualenv environments the Vagrantfile sets up.

When SSHing to Vagrant, use a reverse SSH tunnel to allow the Vagrant environment to connect
back to your host system where the PyCharm remote debugger is listening. ``vagrant ssh`` allows
you to specify arbitrary SSH commands using the ``--`` syntax. Assuming a PyCharm remote debugger
is listening on port 12345, connect to Vagrant with a reverse tunnel using::

$ vagrant ssh -- -R 12345:localhost:12345

You'll also need to configure local to remote path mappings to allow PyCharm to treat your host
code checkout corresponds with the remote Vagrant code. To do this, edit the PyCharm remote
debugger instance and add the following path mapping configuration::

/home/<your_username>/devel=/home/vagrant/devel

Resolving References¶

With Vagrant, Pulp is not installed on your host system preventing PyCharm from knowing an object
through static analysis. Practically speaking, this causes all Pulp objects to be shown as an
unresolved reference and prevents jumping to the declaration (Ctrl + B).

To resolve this, configure your project with a Vagrant-aware, remote interpreter. In settings,
find the 'Project Interpreter' area and add a Remote Interpreter. Select 'Vagrant'
and give it the path to your vagrant file. In my case this is ``/home/<username>/devel/pulp``.

.. note:: The remote interpreter copies the indexed remote code locally into PyCharm's cache.
          Be aware, when you jump to a declaration (Ctrl + B), you are being shown PyCharm's
          cached version. For reading code this is fine, but when applying changes, be sure
          you know if you are editing the actual code or a cached copy.

Use Vagrant's Inventory¶

You may find it convenient to have more manual control
over the running of the playbook by running ``ansible-playbook`` directly against the
Vagrant inventory. Vagrant stores its inventory in a ``.vagrant`` dir in the same place
as the ``Vagrantfile`` after running ``vagrant up``. Vagrant stores the inventory in
``.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory``, so pass that to
``ansible-playbook`` as the invetory when running the dev playbook, remember to also
enable the vagrant role::

ansible-playbook -e ansible_python_interpreter=/usr/bin/python3 -e use_vagrant_role=true \
    -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory \
    ansible/dev-playbook.yml