Skip to main content
\( \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)

Appendix I The PreTeXt Vagrant box

In this appendix, we describe how to install and use the official PreTeXt Vagrant box. Vagrant is a tool that allows for the automatic provisioning and version control of virtual machines. What this means for the PreTeXt user is that there is a quick, simple installation process that is nearly guaranteed to result in a correctly functioning, up-to-date PreTeXt installation. Moreover, this installation simulates the behavior of a native Linux installation while providing access to important files directly to the host operating system. Therefore much of this appendix is written with the assumption that most Vagrant box users are not already running a Unix-like host—i.e.they are running Windows. However, any PreTeXt user may benefit from a sanitized, centrally managed authoring environment.

Prerequisites for installation
  • 64-bit operating system (directions for determining this)
  • VT-X enabled in your BIOS (Intel processors only)
  • PuTTY or other SSH client (I recommend the portable install for PuTTY)

All versions of Windows 10 are 64-bit. If you are running Windows 7, open Windows Explorer and select This PC in the left-hand pane. Right-click and select “Properties”. Examine the dialog for information about whether your Windows is 32- or 64-bit.

On Linux, execute lscpu and look for the line marked “CPU op-modes”.

Mac OS X Lion (10.7) and up are 64-bit. If you are running Snow Leopard (10.6) or earlier, launch System Profiler and click Software (in the Contents section) to check for a 64-bit kernel.

VT-X may already be enabled on your machine, and it may not. If you have an AMD processor, there is nothing to do. Intel machines may need their BIOS reconfigured to run Vagrant. To enter the BIOS menu, restart your machine and watch closely. You will need to hold down a certain key during the boot sequence, often Escape, F2, or F12. As soon as you see the message, press the key and do not release until you see the BIOS menu. I usually have to restart more than once because I'm too slow.

Every motherboard has a different BIOS menu. Just look through all the menus until you find the VT-X option, then enable it and use the “Save changes and exit” option from the main menu. Be careful not to make other changes unless you know what you are doing.

Unix-like operating systems should have ssh installed. Windows users can download PuTTY here (I recommend the single-file installation under “Alternative Binary Files”—just download and run, no installer).

Installation
  1. Download and install Virtualbox
  2. Download and install Vagrant
  3. Open a console (Windows: press Windows key, type cmd)
  4. Create a new directory vagrant_demo and change into it, using the command

    $ mkdir vagrant_demo
    $ cd vagrant_demo
    
  5. Type the commands

    $ vagrant init daverosoff/pretext
    $ vagrant up
    

    This step takes between 30 and 60 minutes to complete. There is a lot of downloading. There will be some interesting messages, but once it gets going you don't have to watch.

  6. Open PuTTY and connect to address 127.0.0.1, port 2222.
  7. Answer “Yes” to the authentication message
  8. Login user/pass: vagrant/vagrant
  9. If you see the prompt [vagrant@archlinux ~] $, congratulations! You have successfully installed the PreTeXt Vagrant box.
  10. Keep the PuTTY window open for use in the next section.
List I.0.1 Steps to install
A first example

Presumably, you already have a project underway. Use your usual file browser or command line to move or copy your project into the vagrant_demo directory you created earlier.

In your PuTTY window, invoke the commands

$ cd /vagrant

$ ls

and observe that your project is there, in your Vagrant box. The /vagrant directory in the Vagrant box is synced to the vagrant_demo directory you created earlier.

Do your normal compilation dance, including steps to build images, HTML, and PDF output. For me it might look like this:

$ cd m101
$ mkdir -p output/images
$ ~/mathbook/script/mbx -c latex-image -d output/images -f all src/index.mbx
$ xsltproc --xinclude --output output/ ~/mathbook/xsl/mathbook-html.xsl src/index.mbx
$ xsltproc --xinclude --output output/ ~/mathbook/xsl/mathbook-latex.xsl src/index.mbx
$ cd output
$ xelatex index.tex

After compilation is done, use your normal file browser to locate the output tree you created. Find some output and preview it, marveling at the simplicity of what has befallen your project.

Remark I.0.2

It is also possible to keep source in the /home/vagrant directory in the Vagrant box. Then the source will not be accessible from the Windows host. One possibility would be to use git to author in Windows and pull changes to the Vagrant box at compile time. I'm not sure why this would be better. Perhaps you don't want multiple copies of your source floating around your main disk drive.

You can halt or suspend your Vagrant box by issuing the vagrant halt or vagrant suspend commands, and destroy all vestiges of it with vagrant destroy. The latter does not remove the image from which the box is cloned, so starting another box later (perhaps in a different location) is much faster.

Known issues

The current build of the Vagrant box includes Sage, Asymptote, and WeBWorK via Docker as described at the wiki. Presumably, if your compilation dance requires a WeBWorK server, then you already have access to one and your normal compilation will still work. It does not yet include jing for validation; this will be included in the next release.

While I have tried to keep the virtual machine image as simple as possible, it is still fairly large, more than 5 GB, and any virtualization will demand a substantial amount of machine memory. Vagrant will run best if you have at least 8 GB of ram. I am interested to hear how well it works on less high-powered systems.

The jing-trang validation tool is not included in the present version.

Thanks for your interest in the PreTeXt Vagrant box. If you encounter errors, or if you think something is missing, please open an issue on Github.