2.1.1.1.1.2. Quick Start Guide: Makahiki on Vagrant

If you have not already installed VirtualBox and Vagrant and downloaded the Makahiki source code, complete Setting Up the Makahiki and Vagrant Development Environment before completing this section.

Note

In this article, a “>” indicates a command prompt on the host OS. Commands appearing after a “>” should work on Windows, OS X, and Linux unless otherwise stated.

Note

The “makahiki>” prompt indicates that the working directory is in the “Makahiki directory” on the host machine. The file path preceding “makahiki” (e.g., “C:\Users\username\Vagrant\makahiki>”) will be different depending on the location of the directory in the file system of the host OS.

If a Command Prompt (Windows) or Terminal (OS X and Linux) shell is not open on your host machine, open one.

2.1.1.1.1.2.1. Set up Makahiki in the Virtual Machine

In your Command Prompt or Terminal, switch your working directory to the “makahiki” directory that was created in Setting Up the Makahiki and Vagrant Development Environment:

> cd <path-to-makahiki>/makahiki

Replace <path-to-makahiki> with the file system path to the “makahiki” directory. On Windows, if your “makahiki” directory is located at C:\Users\username\Vagrant\makahiki, you would use the command cd C:\Users\username\Vagrant\makahiki here. On Linux, if your “makahiki” directory is at /home/username/vagrant/makahiki, you would use the command cd /home/username/vagrant/makahiki here.

A Windows example:

_images/windows-command-prompt-vagrant-switch.png

The “makahiki” directory was created when you cloned the Git repository in Setting Up the Makahiki and Vagrant Development Environment. It contains the Vagrantfile which defines the settings of the Vagrant virtual machine. It also contains all of Makahiki’s source code.

Use the vagrant up command to start the virtual machine for the first time:

makahiki> vagrant up

Warning

Windows users may see multiple warnings while vagrant up is running for the first time.

  • A Windows Firewall warning about vboxheadless.exe: This application should be allowed.
  • VirtualBox is attempting to make changes to the system: This should be allowed. It is needed for Vagrant / VirtualBox host-only networking to work.

Warning

If your Vagrant version is less than 1.3.0, you are starting your virtual machine for the first time, and you do not want to lose your configuration, start Vagrant with --no-provision:

makahiki> vagrant up --no-provision

In Vagrant versions prior to 1.3.0, each time Vagrant is started with vagrant up, it will run the run_bootstrap.sh provisioning script specified in the Vagrantfile. This runs another script, bootstrap.sh, which:

  • Sets the system locale to en_US.UTF-8
  • Drops the PostgreSQL cluster data directory, erasing all data in all databases
  • Re-initializes the cluster data directory
  • Re-initializes the Makahiki database

The run_bootstrap.sh script logs the output of bootstrap.sh to a file in makahiki/vagrant/logs. This file will be called “ubuntu_x86_<timestamp>.log,” where timestamp is a string in the format yy-mm-dd-HH-MM-SS (year, month, day, hour, minute, second).

When the script finishes running, look at the last few lines of output:

-------------------------------------------------------------------------------
Configuration setup results:
-------------------------------------------------------------------------------
1. Copying locale settings to /etc/bash.bashrc: [Succeeded]
2. Copying settings to pg_hba.conf: [Succeeded]
3. Creating /home/vagrant/makahiki_env.sh: [Succeeded]
4. Appending to /home/vagrant/.bashrc: [Succeeded]
-------------------------------------------------------------------------------

If the value for a task is “Succeeded” or “Already completed,” continue to the next step. If the value for a task is “Failed,” go to Troubleshooting Makahiki on Vagrant.

2.1.1.1.1.2.2. Connect to the Vagrant Virtual Machine

Start an SSH session with the Ubuntu virtual machine:

makahiki> vagrant ssh

An Ubuntu command prompt will be displayed:

vagrant@precise32:~$

2.1.1.1.1.2.3. Start the Server

Note

The /vagrant directory that contains /vagrant/makahiki is a special directory that is synchronized with the “makahiki” directory (folder) on your host OS.

  • Any file added to /vagrant on the virtual machine will be added to makahiki on the host machine.
  • Any file added to makahiki on the host machine will be added to /vagrant on the virtual machine.

To start one of the two web servers that Makahiki provides, switch to the /vagrant/makahiki directory:

vagrant@precise32:~$ cd /vagrant/makahiki

The two servers are runserver, which is better for development, and gunicorn, which is better for production use.

To start the runserver server:

vagrant@precise32:/vagrant/makahiki$ ./manage.py runserver 0.0.0.0:8000

Example output of starting runserver:

vagrant@precise32:/vagrant/makahiki$ ./manage.py runserver 0.0.0.0:8000
Validating models...

0 errors found
Django version 1.4, using settings 'settings'
Development server is running at http://0.0.0.0:8000/
Quit the server with CONTROL-C.

To start the gunicorn server:

vagrant@precise32:/vagrant/makahiki$ ./manage.py run_gunicorn -b 0.0.0.0:8000

Example output of starting gunicorn:

vagrant@precise32:/vagrant/makahiki$ ./manage.py run_gunicorn -b 0.0.0.0:8000
Validating models...
0 errors found

Django version 1.4, using settings 'settings'
Server is running
Quit the server with CONTROL-C.
2013-10-11 01:59:41 [1399] [INFO] Starting gunicorn 0.13.4
2013-10-11 01:59:41 [1399] [INFO] Listening at: http://0.0.0.0:8000 (1399)
2013-10-11 01:59:41 [1399] [INFO] Using worker: sync
2013-10-11 01:59:41 [1408] [INFO] Booting worker with pid: 1408

2.1.1.1.1.2.4. Verify that Makahiki Is Running

Open a browser on the host machine and go to http://192.168.56.4:8000 to see the landing page, which should look similar to this:

_images/kukui-cup-demo-landing.png

In the virtual machine, stop either server with control-c when you are finished:

vagrant@precise32:/vagrant/makahiki$ (type control-c in the shell running the makahiki server process)

If the site is not reachable from your host machine, or your host machine is headless and has no GUI, refer to Running Makahiki on Vagrant and follow the section on Testing the Server Without a Web Browser.

2.1.1.1.1.2.5. Makahiki Maintenance Tasks

The basic installation of Makahiki is now complete.

To learn how to reset or update the Makahiki database, continue to Running Makahiki on Vagrant.

2.1.1.1.1.2.6. Exit Your SSH Session

When you are finished working with the Vagrant virtual machine, end your SSH session by typing exit in the SSH terminal:

vagrant@precise32:/vagrant/makahiki$ exit

On your host OS, you will be returned to the terminal that started the SSH session.