Arches (http://archesproject.org) is an open source geospatial information system built to aid in the management of heritage resources. We’ve been getting a lot of interest in setting up the Arches system for various use cases. As such, I wanted to start what will hopefully become a series of posts on how to set up the Arches system for a variety of use cases and environments.
Since my role on the project has been as an application developer, I’ll begin with the process that I’m most familiar with, which is setting up a development environment. There are lots of ways in which one could set up an Arches development environment (for example, I personally have been running Arches natively in OSX for the last couple months with much success), and in time hopefully we can cover many of these options.
I would like to start, however with what I believe is the simplest solution and one that should work across many different operating systems. This approach will use Vagrant (http://vagrantup.com) and VirtualBox ( https://www.virtualbox.org/) to generate an Ubuntu virtual machine that will run the Arches system. Using Vagrant makes development easy because you can run your project out of a well known environment while testing and writing code in your preferred operating system. Vagrant allows you to edit code locally and automatically syncs the code to your virtual machine and allows you to forward ports from your virtual machine to your host machine so that you can access resources on your virtual machine from your host machine (for example, a web server or database). For more on exactly how to develop using a Vagrant generated virtual machine, see the Vagrant ‘Getting Started’ guide (http://docs.vagrantup.com/v2/getting-started/index.html).
We’ve tried to make setting up an Arches virtual machine for development as easy as possible. Towards this end, the Arches repository includes a Vagrantfile that is preconfigured to install the dependencies and configure the relevant port forwarding. Setting up an Arches development environment includes the following steps (I will include the relevant shell commands for a *-nix system; these commands assume you will be storing the Arches code in ~/projects/arches):
- Install Mercurial (http://mercurial.selenic.com/), Vagrant ( http://vagrantup.com), and VirtualBox (https://www.virtualbox.org/).
These installations can be performed by following the steps outlined for each of these products on their web sites.
- Clone the repositories
We’ll need to retrieve the Arches code from the relevant BitBucket repositories. Arches requires a ‘package’ to run properly, so we will need to clone both the Arches repository as well as the Arches CDS Package repository.
Shell commands:
machine_name:~ user$ hg clone https://bitbucket.org/arches/arches projects/arches
machine_name:~ user$ hg clone https://bitbucket.org/arches/cds projects/arches/archesproject/packages/cds
- Add the vagrant ‘base box’.
In order for Vagrant to set up a virtual machine, it requires a ‘base box’ be added that will be used as a starting point for your new virtual machine. For Arches, we’ve been using the precise32.box base box provided by Vagrant.
Shell commands:
machine_name:~ user$ vagrant box add precise32 http://files.vagrantup.com/precise32.box
- Configure Arches package settings.
The Arches software will need to be configured to use the CDS package that we’d cloned in step 2. This can be done easily by creating a settings_local.py file in the project root directory and adding “INSTALLED_PACKAGES = (‘cds’,)”
Shell commands:
machine_name:~ user$ touch projects/arches/settings_local.py
machine_name:~ user$ echo “INSTALLED_PACKAGES = (‘cds’,)” >> projects/arches/settings_local.py
- Create the virtual machine.
Now it’s time to create and boot up our virtual machine. The Arches Vagrantfile is also set up to run the required scripts to install all the dependencies and build Arches on the newly created virtual machine.
Shell commands:
machine_name:~ user$ cd projects/arches
machine_name:arches user$ vagrant up
- Turn on the development server.
For development purposes, we have been using the Django built in development server for running the web app. To turn the server on, you will first need to ssh into your newly created virtual machine. From there, we’ve created a script (runserver-vagrant.sh) that will run the necessary commands for turning the server on.
Shell commands:
machine_name:arches user$ vagrant ssh
vagrant@precise32:~$ cd /vagrant
vagrant@precise32:/vagrant$ ./runserver-vagrant.sh
(I’ve created a Gist containing the full output log from the above commands that is available here: https://gist.github.com/robgaston/10031103)
You should now have your virtual machine up and running with the Django development server running. Since the port forwarding should already be set up, you should be able to access the Arches web site by going to http://localhost:8000/Arches from your host machine.
Happy coding!
