Using the Vagrant VM

Using The Vagrant VM

You've probably already noticed a Vagrantfile at the root of the git repository. This Vagrantfile can be used to fire up a VM with everything needed to build the RTD website with materials from GitHub and Google Docs.

You'll need at least Vagrant 2.0.1 and VirtualBox 5.1.x installed to get started.

Working Directory

The Vagrantfile maps the current project directory on the host . to /readthedocs on the guest VM. This is where all the work is done. This is where the documents are downloaded from the readthedocs folder in a Google Drive and merged into the hierarchy. Upon a vagrant ssh you'll be in the subutai user's home directory, so do not be surprised if you do not find anything associated with the documentation there.

VM Configuration

There are a few configuration tasks that need to be taken care of to properly use this VM. If you do not have a token bearer file available or don't even know what that is, go ahead and fire up the VM even though there will be some problems.

vagrant up

The VM sets up a Google Drive CLI client while provisioning. If you do not specify an environment variable called GDRIVE_TOKEN_FILE, either on the command line, or export it in your shell's profile file, then you'll get the following warning at the end of the provisioning step:

==> default: Running provisioner: shell...
    default: Running: inline script
    default: Google drive client could not initialize.
    default:
    default: Setup bearer token file and re-provision with vagrant.
    default: Will NOT attempt site generation or start sphinx auto
    default: build daemon. See the following wiki for more information:
    default:
    default: https://github.com/subutai-io/docs/wiki/Using-the-Vagrant-VM
    default:
    default: Existing with non-zero status.
The SSH command responded with a non-zero exit status. Vagrant
assumes that this means the command failed. The output for this command
should be in the log above. Please read the output to determine what
went wrong.

Let's create the bearer token file

We're going to create the token file, save it somewhere safe, and setup this GDRIVE_TOKEN_FILE environment parameter to point to it. Follow these steps with the VM up:

1. Go ahead and vagrant ssh into the VM in a shell
2. Once inside as the subutai user execute the command gdrive about
3. You'll get prompted by a long assed URL to get a verification token. Copy that URL and paste it into a browser. You will be asked to authenticate into your Google Drive and you'll get a verification code. Copy that from the browser.
4. Paste the verification code into the shell and hit return. This will generate the following file: /home/subutai/.gdrive/token_v2.json.
5. Copy /home/subutai/.gdrive/token_v2.json to /readthedocs with the following command to transfer it to your root directory. WARNING: Whatever you do be very careful not to commit it to this repository 👎 .
6. Exit the shell.

Now you have a bearer token file in the host system right in the root of the project. Let's move it over to somewhere safe. The best place is where you keep your ssh security credentials since the directory is mod 700. Issue the following commands:

if [ ! -f $HOME/.ssh ]; then
  mkdir -p $HOME/.ssh
  chmod 700 $HOME/.ssh
fi

mv ./token_v2.json $HOME/.ssh
chmod 600 $HOME/.ssh/token_v2.json
export GDRIVE_TOKEN_FILE=$HOME/.ssh/token_v2.json
vagrant provision

If everything goes well, then you'll see the output look something like this: of course with different values for your account. This means your account access to your google drive is configured.

    default: 2018-01-17 13:15:00 (1.72 MB/s) - ‘/usr/local/bin/gdrive’ saved [7805504]
    default: net.ipv4.conf.enp0s8.route_localnet = 1
==> default: Running provisioner: file...
==> default: Running provisioner: shell...
    default: Running: inline script
    default: User: Joe Dirt, jd@foobar.com
    default: Used: 5.3 GB
    default: Free: 26.9 GB
    default: Total: 32.2 GB
    default: Max upload size: 5.2 TB

If you have not setup the GDRIVE_RTD_ROOT environment variable with the identifier of the readthedocs root in your Google Drive, this will tell you to do so if it finds such a folder in a listing. If it cannot then you will have to set the value yourself. You can export this value in your shell's profile file.