This is a guide for people who wish to use the public Formhub Virtual Disk Image (VDI) to run their own instance(s) of Formhub on VirtualBox with minimal fuss.

The public Formhub VDI is a pre-built server image which contains everything necessary to run Formhub in a stable, self-contained virtual machine environment.

The public Formhub VDI is based on the current master source code branch, implemented in debian and postgresql.

1. Install VirtualBox

Download and install the VirtualBox binary appropriate for your computer.

2. Obtain the public Formhub VDI

Download the VDI file (the latest version is Formhub-Public-VDI-v.0.0.2.vdi.bz2) to your computer, unzip it, and make sure to note where the unzipped .vdi file is saved.

1. Start VirtualBox and tap the New button on the top left

2. Give your VM a name, and choose Linux and Debian for the type and version

You can leave the next screen (memory size) as-is, unless you have a special reason for adding more memory and/or your computer can accomodate it.

3. Choose the public Formhub VDI for the hard drive

Use the yellow folder select icon on the bottom right to find the Formhub VDI file you downloaded to your computer and click the Create button.

4. Before turning it on for the first time, make sure your VM network is set to Bridged Adaptor, and pick eth0, wlan0, etc. as appropriate

5. Start the VM

When it finishes booting, everything will be up and running automatically, and so if you visit the IP address where the VM is running (check your LAN/local router settings once it has booted), you should see the Formhub home page:

Unlike running the public Formhub AMI on AWS, signing up new users will work, except the email Formhub sends for validation goes nowhere, which brings us to the last major step.

6. Stopping the VM

To avoid problems with monogodb not starting correctly on boot, always shut down the VM as user root using the shutdown command like this:

shutdown -h now

Out of the box, Formhub will write all user-submitted data to the /home/fhuser/formhub folder.

If you would prefer to use a different location, edit the /home/fhuser/formhub/formhub/preset/default_settings.py file, and insert a line to redefine the MEDIA_ROOT variable, for example like this:

MEDIA_ROOT = '/opt/data/formhub/userdata'

You need to make sure that whatever you define here exists on the file system, and that the fhuser account has permission to write to it. Read more about MEDIA_ROOT and how managing stored files works in django.

By default, django uses example.com as the DNS name of your server.

Among other things, what this means is that the various automated emails formhub sends (e.g., after account registration, password reset, etc.) will point to an address on example.com instead of your site.

To change this, login as user fhuser and type the following terminal commands to get to a django shell:

fhuser@ip-10-69-144-231:~$ cd formhub
fhuser@ip-10-69-144-231:~/formhub$ python manage.py shell 

If successful, you should be greeted by this message, and the django shell prompt:

Your environment is:"formhub.preset.default_settings"
Python 2.7.3 (default, Mar 13 2014, 11:03:55)
[GCC 4.7.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>>

At the shell prompt, type these commands, and replace myrealdomain.com with the domain name or elastic ip address you are using:

>>> from django.contrib.sites.models import Site
>>> current_site = Site.objects.get_current()
>>> current_site.domain = 'myrealdomain.com'
>>> current_site.name = 'myrealdomain.com'
>>> current_site.save()

Hit control-d or type exit() to exit the django shell.

If you wish to use django's automatic admin interface for formhub, you will need to create an administration user account, or superuser.

Login to your instance as user fhuser and type the following terminal commands to get to the createsuperuser command:

fhuser@ip-10-69-144-231:~$ cd formhub
fhuser@ip-10-69-144-231:~/formhub$ python manage.py createsuperuser 

You will greeted with the following interactive prompt. Just provide a username, email, and password when asked:

Username: ImAsuperUser
Email address: [email protected]
Password:
Password (again):
Superuser created successfully.

With the superuser account created successfully, you should be able to login to the django admin interface at http://myrealdomain.com/admin (more about the django admin interface).

Edit the /home/fhuser/formhub/formhub/preset/default_settings.py file, to redefine the DEFAULT_FROM_EMAIL and EMAIL_HOST variables.

DEFAULT_FROM_EMAIL = '' # e.g., '[email protected]'
EMAIL_HOST = '' # e.g., 'mail.example.com'

The former is the email address used to send automated emails (e.g., account registration confirmations, automated password resets, etc.), and the latter is the name of the server sending outgoing email (see the instructions in the next section, Configure Outgoing Email, for what to use here).

Optionally, you can also edit the EMAIL_HOST_USER to be an email address different from the one used for DEFAULT_FROM_EMAIL, which is the default.

EMAIL_HOST_USER = DEFAULT_FROM_EMAIL # may be different

This section uses postfix as the outgoing mail agent, so that emails generated from the Formhub (after sign up, for password changes, etc.) get delivered correctly.

The instructions in this section are based on http://www.davidgrant.ca/setting_up_postfix_to_send_outgoing_mail_on_ubuntu

1. Once the VM has booted, login at the prompt as either user root, or fhuser and then use sudo to become root.

   The password for both accounts is set to all4one but you should change those using the passwd command, later.

There is also a graphic window manager available (run startx as user fhuser) but the is not necessary for configuring outgoing email.

2. Configure Postfix on the VM

While postfix has already been installed, you will need to change its configuration to operate with your ISP's outgoing email server.

Run dpkg-reconfigure postfix as the root user:

3. Choose the Satellite option

Satellite assumes your VM will use the same ISP and network as the computer on which VirtualBox is running. If that is not the case, you may need a different configuration type.

4. Define your network's Fully-Qualified Domain Name (FQDN)

5. The Crucial Part

Check with your ISP what the exact server name or IP address and port settings should be here.

6. Make fhuser the email target

7. Use the defaults for the remaining questions

Unless you have a specific reason to change something, leave all the defaults as-is, as shown here.

8. Test it

Postfix will restart automatically, and if the settings are correct, outgoing email sent by Formhub should work.

You can also test it right there at the prompt by typing this command (replace [email protected] with your actual email address):

echo test | mail -s "Just confirming FH mail" [email protected]

If all is well, you should get an email with subject Just confirming FH mail in your inbox.

If something is wrong, check with your ISP for the correct SMTP settings for setup 5, and run dpkg-reconfigure postfix as root again.