Using Vagrant

Vagrant is a command line utility for creating project-specific virtual machines (VMs).
MedaCy uses Vagrant to enable development on different platforms, including Windows.
This guide will instruct you on how to use Vagrant within PyCharm or from the command line.

Installations

The only additional software you need to use Vagrant is VirtualBox and Vagrant itself.
This guide assumes that if you plan to use PyCharm, you have the professional edition
and are already familiar with how to use its base features.
The full user guide for PyCharm can be found here.

Installing VirtualBox

VirtualBox is an open-source program for creating virtual machines.
Vagrant will utilize it to create your medaCy virtual machine.
You can download the version appropriate for your machine here
and follow the installation instructions that they provide.

Installing Vagrant

Go to the installation page for Vagrant and select the version
appropriate for your machine. You will likely need to restart your machine after this step.

Please also run this command to allow for the customization of the Vagrant box's disk size:

$ vagrant plugin install vagrant-disksize

Vagrant for medaCy

Each project that uses Vagrant requires there to be a file in the root directory of the project named
Vagrantfile. MedaCy distributes with this file already configured.

At the command line

Vagrant up

This step includes downloading an Ubuntu operating system and should be performed with a strong internet
connection for fastest results.

From the command line, navigate to the directory containing your clone of medaCy, and run this command:

$ vagrant up

This command will create your new medaCy VM using the specifications in the Vagrantfile.
You will be using this command every time you want to start up your VM,
but since this is its first activation, it will take a while.
While you wait, the operating system for the medaCy VM (Ubuntu), Python 3, and medaCy and all its dependencies
are being downloaded and installed. Once these downloads complete,
you won't have to wait for them every time you run vagrant up.

Let's take a look

Now run:

$ vagrant ssh

When this command finishes, you'll be inside your new VM. Specifically, you'll be in the home folder.
You don't particularly need to be here, so run these commands:

vagrant@ubuntu-bionic:~$ cd ../..
vagrant@ubuntu-bionic:/$ cd vagrant
vagrant@ubuntu-bionic:/vagrant$ ls

After running the first command, you could run ls to see the root directory of your
VM, if you feel so inclined. We're interested in what's in the /vagrant subdirectory.
The /vagrant directory of the VM contains your copy of the medaCy repository, and is shared between the
VM and the directory on the host machine containing the Vagrantfile.

So should I continue by setting up a virtual environment for medaCy?

No. Think of your VM as an enhanced virtual environment. When the VM was created, medaCy
and all of its dependencies were installed on the base installation of Python 3.
In theory, you'll only be using this VM for medaCy, so there's no need to
create a separate environment for it.

Because of how Python 3 was installed on the VM, you will need to use the command Python3 rather than Python,
and pip3 instead of pip; pip3 may require using sudo.

What now?

Now that you have a medaCy-specific Ubuntu VM with a shared folder between the VM and your machine,
you can edit any file you'd like in whatever text editor you choose, then run it within the VM from
the command line. You won't need to worry about whether or not medaCy is compatible with your host machine.

Keep in mind that the VM has limited resources and should only be used for developing
medaCy itself and generating predictions. Model training requires significantly more resources and
should be done on a machine with a significant amount of memory.

Exiting and turning off the VM

Having a VM running requires a lot of resources from your host machine. When you're
done using the VM, run these commands.

vagrant@ubuntu-bionic:~$ exit
$ vagrant halt

$ exit will leave the VM from the command line but leave it running in the background;
$ vagrant halt will turn it off.

In PyCharm

Tools > Vagrant > Up

PyCharm Professional Edition provides features for interacting with Vagrant VMs.
This guide will cover the basics, but the developers of PyCharm provide a guide here.

Open your medaCy project in PyCharm and select Tools > Vagrant > Up. This is the same
as running vagrant up from the terminal.

Tools > Start SSH session...

Likewise, Tools > Start SSH session... is the same as $ vagrant ssh. PyCharm will list
your Vagrant VM as an option to SSH into. You will then be able to interact with the VM at
its own terminal.

From Tools > Vagrant, you also have the option to select Halt.

Configuring the interpreter

While you're developing medaCy in PyCharm, you probably don't want to run each script from the command line.
This section details how to set the project interpreter to be the installation of Python 3 on the VM.

Select File > Settings, and then on the settings menu, select Plugins. Enable the
Remote Interpreter plugin.

Once remote interpreters are enabled for PyCharm, you will need to configure the remote interpreter
for this project. The plugin is already designed to work with Vagrant, so this will be easy.

Again, go to File > Settings, and select Project: medacy > Project Interpreter. Select the gear
icon on the right side of the dialogue box and select "add". Another dialogue box will appear.
Select "Vagrant" on the left side of the new box. Set the Python interpreter path to
usr/bin/python3.

Finishing up

We hope that this guide was able to clarify how to configure Vagrant for medaCy.
Should you encounter any issues, please follow the links throughout the guide
to read the documentation for Vagrant and PyCharm. If you believe the problem is
specific to Vagrant is configured for this project, please open a new issue.