Pulp

# 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

~~~