Getting started

From Archivematica
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.


The recommended way to install Archivematica for development is with Ansible and Vagrant.

Ansible & Vagrant

The following instructions detail how to install and run Archivematica from source on a virtual machine.

  1. Install VirtualBox, Vagrant, and Ansible with the following commands:
    • sudo apt-get install virtualbox vagrant (this is the command for Ubuntu; if you use Mac or Linux, it may be slightly different).
      • Note: Vagrant must be at least 1.5 (it can also be downloaded from Check your version with vagrant --version.
    • sudo pip install -U ansible
  2. Checkout the deployment repo:
  3. Download the Ansible roles:
    • cd deploy-pub/playbooks/archivematica
    • ansible-galaxy install -f -p roles/ -r requirements.yml
  4. (Optional) Change the branch by opening the file vars-singlenode.yml and modifying the following:
    • archivematica_src_am_version: "branch-name"
    • archivematica_src_ss_version: "branch-name"
  5. Create the virtual machine and provision it:
    • vagrant up (it takes a while!)
  6. You can now log in to your virtual machine:
    • vagrant ssh
  7. You can now access the following services in a web browser:

You may also wish to do the following.

  1. Provisioning (via ansible) can be re-run with vagrant to update the code on the server (for example, if new features are added):
    • vagrant provision
  2. To re-deploy a new branch to the same VM, update the branch variables in vars-singlenode.yml:
    • archivematica_src_am_version: "branch-name"
    • archivematica_src_ss_version: "branch-name"
      • This will probably require resetting the Archivematica installation as well. This can be done by adding variables to vars-singlenode.yml
    • archivematica_src_reset_am_all: "true" This will reset the Archivematica database, clear ElasticSearch and clear shared directories
    • archivematica_src_reset_ss_db: "true" This will reset the Storage Service database
    • For more variables to control deployment, see the README
  3. See also the FAQ below

Local install (Legacy)

Archivematica can also be installed locally on a development machine using dev-helper. See development environment setup instructions This is considered legacy, and we recommend using Vagrant and Ansible.

Alternative Vagrant projects

Community-provided alternatives have also been developed.


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


  • How do I restart everything in Archivematica?

A default install using Ansible also installs the devtools. Run am restart-services to restart all services related to Archivematica and the storage service.

  • How do I restart just the dashboard?

sudo /etc/init.d/apache2 start or sudo service apache2 restart

  • How do I restart the storage service?

sudo service uwsgi restart

  • How do I restart nginx?

sudo service uwsgi restart sudo service nginx restart

  • How do I update or reset an ansible install?

To update an install, re-run vagrant provision. If you only want to run part of the ansible tasks, you can use ansible's tags, for example: env ANSIBLE_ARGS="--tags=amsrc-ss-code" vagrant provision More tags are documented in the ansible repo

To reset an install (delete all existing data like a fresh install) you can use ansible's role variables. For example: env ANSIBLE_ARGS="--extra-vars=archivematica_src_reset_ss_db=true" vagrant provision will reset the storage service database. More role variables are documented in the ansible repo

The other way to control a deployment is to modify the Vagrantfile and vars-singlenote.yml files directly. Tags can be provided in the Vagrantfile. For example:

# ... more above
  # Ansible provisioning
  config.vm.provision :ansible do |ansible|
    ansible.playbook = "./singlenode.yml"
    ansible.host_key_checking = false
    # ansible.verbose = "v"
    ansible.extra_vars = {
      "archivematica_src_dir" => "/srv",
      "archivematica_src_environment_type" => "development",
    ansible.raw_arguments = ENV['ANSIBLE_ARGS']
    ansible.tags = ['amsrc-pipeline']
# ... more below

Role variables can be modified in vars-singlenote.yml. Default values are found in the Archivematica role (in roles/archivematica-src/defaults/main.yml). For example:


# archivematica-src role

# What to install
archivematica_src_install_devtools: "yes"
archivematica_src_install_automationtools: "yes"
# archivematica_src_install_appraisaltab: "yes"

# SS django environment variables
archivematica_src_ss_env_django_setings_module: "storage_service.settings.local"

# Branches,
archivematica_src_am_version: "qa/1.x"
archivematica_src_ss_version: "qa/0.x"
# archivematica_src_devtools_version: "master"
# archivematica_src_automationtools_version: "master"

# Reset
# archivematica_src_reset_mcpdb: "true"
# archivematica_src_reset_shareddir: "true"
# archivematica_src_reset_es: "true"
archivematica_src_reset_am_all: "true"
archivematica_src_reset_ss_db: "true"