softcover-vagrant

A Vagrantfile for use with the Softcover publishing platform

Vagrantfile and README originally prepared 29 October 2015 by Mike Weilgart

Instructions for using the Vagrantfile:

1. If you haven't installed vagrant and virtualbox, do so.

2. Clone this project to your local box

   git clone git@github.com:mikeweilgart/softcover-vagrant.git

3. Change directories into the project.

   cd softcover-vagrant

4. Run the following very long running command (read on before you do it!)

   vagrant up

   This will take roughly an hour and a half, as it will first download a minimal basebox, then download and install ALL software needed to run softcover, including the several GB worth of tex packages. Do it with a good internet connection. Run it as time vagrant up if you're curious how long it will take.

5. Log in to the vagrant box:

   vagrant ssh

   You are now logged in to the vagrant box. Don't do your work yet, though!

   The point of Vagrant is a disposable, reproducible virtual environment. You don't want to run a 90 minute command every time you need to refresh your environment! So next we'll repackage this vagrant box for later reuse.

6. If you want other packages to be available on your system each time you vagrant up, install them now. For example:

   sudo apt-get -y install vim
   sudo apt-get -y install git

7. Do the following to make your vagrant box as small and clean as possible for repackaging:

   sudo apt-get clean
   sudo dd if=/dev/zero of=/EMPTY bs=1M
   sudo rm -f /EMPTY
   cat /dev/null > ~/.bash_history && history -c && exit

8. Do the following (on your host system, of course) to repackage your box:

   vagrant package --output softcover-ubuntu-14.04.box

9. Do the following to add the box to your system in vagrant and make it usable:

   vagrant box add softcover-ubuntu-14.04 softcover-ubuntu-14.04.box

   After you've done this the softcover-ubuntu-14.04.box file will not be used again. However you can save it if you want to by skipping the next step. (If you are setting up this vagrant environment for a whole team of people, this box is the file you should distribute! It's not included in this git repository because it is almost 3 GB.)

10. Remove the box now that it's been added and vagrant is storing it elsewhere:

    rm softcover-ubuntu-14.04.box

11. Clean up the box we used for provisioning:

    vagrant destroy

12. Make a new folder where you will have the new vagrant box, cd into it and initialize your new vagrant box using the packaged VM you've just created:

    mkdir -p /path/to/new/vagrant/location/my-softcover-box
    cd /path/to/new/vagrant/location/my-softcover-box
    vagrant init softcover-ubuntu-14.04

You can now vagrant up and vagrant destroy all you want, and softcover and asciidoc will be fully usable from the moment you vagrant ssh. The directory on your host computer where the Vagrantfile is stored will be accessible from the guest as /vagrant and I recommend keeping all softcover project directories in there.

Acknowledgements

The following web pages were extremely helpful in preparing the Vagrantfile and these installation instructions:

• http://blog.hostilefork.com/mobi-pdf-epub-softcover-ubuntu/
• https://scotch.io/tutorials/how-to-create-a-vagrant-base-box-from-an-existing-one