Installing the Virtual Machine#

Warning

ODK Aggregate is no longer being updated. Please use ODK Central instead.

This document provides instructions for installing ODK Aggregate using the Virtual Machine (VM) and VirtualBox.

Setting up the VM#

  1. Download and install VirtualBox.

  2. Download the latest Aggregate VM from the GitHub releases page and unzip the file.

  3. Double-click the OVA file inside the zip to let VirtualBox import the VM. Accept the default settings.

  4. After the import completes, start the VM. Select it with your mouse and click on the Start button on the VirtualBox top toolbar. A new black and white window will open.

  5. After the VM starts, wait for Welcome to ODK Aggregate VM message to appear.

  6. Do not log into the screen of the VM. Instead, on your computer, open a web browser.

  7. Go to the web address shown in the VM screen. (Usually http://localhost:10080.) If everything worked, you will see the Aggregate login screen.

  8. Sign in with Aggregate password

    username: administrator
    password: aggregate

  9. Aggregate will remind you to change your administrator user's password. Please choose a secure password!

Tip

Once VirtualBox has imported the VM, the zip file and the OVA file can be deleted.

Note

  • Read the Running your virtual machine manual page to learn more about working with VirtualBox and your Aggregate VM.

  • Windows: if you get an VirtualBox error message with "File is busy" or "File access error" after launching the VM, it is likely due to improper unzipping or write permissions. Try right-clicking the zip file, then select "Extract All" and save the files to a folder on the Desktop.

  • Linux: if you get a VirtualBox error message about "PAE: Unable to boot", make sure VirtualBox has PAE/NX enabled. That setting is usually under System/Processor.

Securing the VM#

The Aggregate VM is configured with a default root user password which is not secure. Before using the VM with important data, we recommend you log in and change the default password.

  1. Start the VM. When the VM has finished booting up, you will be prompted to log into the VM.

  2. Click on the screen to capture your mouse and keyboard.

  3. Log into the command line interface with the following credentials:

username: root
password: aggregate

  1. You will be forced to change the default password the first time you login. Please choose a secure password!

  2. Once you have logged in, you can exit the command line interface with the exit command.

Note

Make sure you understand how VirtualBox captures your mouse and keyboard and how to release them.

Connecting to the VM from external apps#

The VM defaults to a NAT network adapter, so you will only be able to connect to it from your computer. This is the default behavior because it is the safest configuration.

If you'd like to connect to the VM from an external device (for example, ODK Collect on your phone or ODK Briefcase on another computer), you must set a fully qualified domain name (FQDN) or globally accessible address.

Tip

Aggregate's form download (but not form listing) relies on the FQDN. If you want to use Collect and Briefcase to interact with Aggregate, you must set the FQDN.

To set the FQDN, do the following:

  1. Secure the VM.

  2. Change the VM's network adapter settings in VirtualBox from NAT to Bridged and reset/reboot the VM.

  3. After the reset/reboot, the VM will behave like any other machine on your network and get an IP address from your router. The IP address will be shown to you after the Welcome to ODK Aggregate VM message.

  4. Log into the command line interface of the VM and run the aggregate-config script to set a fully qualified domain name (FQDN) using the IP address that was shown to you (e.g., 192.168.5.2).

aggregate-config --fqdn 192.168.5.2 --http-port 8080 --https-port 8443 --net-mode bridge

  1. After the configuration, use your host computer or any other computer on your network to log into Aggregate at the FQDN and port (e.g., http://192.168.5.2:8080).

Note

Learn more about VirtualBox's networking options.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No