Getting started

From Archivematica
Revision as of 19:21, 19 April 2016 by Hbecker (talk | contribs) (→‎Ansible & Vagrant: remove remotes/origin from branch names)
Jump to navigation Jump to search

Main Page > Development > Getting Started

This wiki page describes getting started with Archivematica as a developer. For user and administrative manuals, please see

Vital Stats


Archivematica consists of several projects working together.

  • Archivematica: Main repository containing the user-facing dashboard, task manager MCPServer and clients scripts for the MCPClient
  • Storage Service: Responsible for moving files to Archivematica for processing, and from Archivematica into storage
  • Format Policy Registry: Submodule shared between Archivematica and the Format Policy Registry (FPR) server that displays and updates FPR rules and commands

There are also several smaller repositories that support Archivematica in various ways. In general, you will not need these to develop on Archivematica.


There are two main ways to run Archivematica in development.

  1. Use ansible and vagrant to install Archivematica in a VM
  2. Install Archivematica on your development machine
  3. Alternate vagrant based installations exist as well

Ansible & Vagrant

To install and run Archivematica from source on a VM:

  1. Checkout deployment repo
  2. Install VirtualBox, Vagrant, Ansible
    • sudo apt-get install virtualbox vagrant
    • Vagrant must be at least 1.5 (it can also be downloaded from
      • vagrant --version
    • sudo pip install -U ansible
  3. Download Ansible roles
    • ansible-galaxy install -f -r requirements.yml
  4. (Optional) Change the branch by modifying vars-singlenode.yml
    • amdev_version: "branch-name"
    • ssdev_version: "branch-name"
  5. Create virtual machine and provision it
    • vagrant up (it takes a while)
  6. Login now available via:
    • vagrant ssh
  7. Services available:
  8. Provisioning (via ansible) can be re-run
    • vagrant provision
    • Or with ansible directly ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory singlenode.yml -u vagrant --private-key .vagrant/machines/am-local/virtualbox/private_key [--extra-vars=archivematica_src_dir=/path/to/code] This allows you to pass ansible-specific parameters, such as --start-at="name of task"

Development Machine

See development environment setup instructions

Alternative Vagrant projects


Archivematica and the related projects have a small but growing test suite. We use py.test to run our tests, which should be listed as a requirement in the development/local requirements file.

To run the tests, go to the repository root and run py.test

See below for project-specific setup or changes to running the tests.


Before running Archivematica tests, set the following environment variable.

set -xg PYTHONPATH /usr/share/archivematica/dashboard/:/usr/lib/archivematica/archivematicaCommon/
export PYTHONPATH=$PYTHONPATH:/usr/share/archivematica/dashboard/:/usr/lib/archivematica/archivematicaCommon/

Storage Service

Before running Storage Service tests, set the following environment variables

set -xg PYTHONPATH (pwd)/storage_service  # The project root
set -xg DJANGO_SETTINGS_MODULE storage_service.settings.test
export PYTHONPATH=$(pwd)/storage_service  # The project root
export DJANGO_SETTINGS_MODULE=storage_service.settings.test