This wiki page describes getting started with Archivematica as a developer. For user and administrative manuals, please see http://www.archivematica.org.
- Language: Python (primarily)
- License: AGPL
- VCS: git
- Major libraries: Django, gearman (Python API)
- Contribution guidelines
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.
- Development tools: Scripts to help with development. E.g. restarting services, workflow analysis
- FPR tools: All the tools, commands and rules used to populate the FPR database. Changes to the FPR should be submitted here.
- Archivematica Documentation: Documentation found at https://www.archivematica.org/en/docs/ for Archivematica
- Storage Service Documentation: Documentation found at https://www.archivematica.org/en/docs/ for the Storage Service
- Automation Tools: Scripts used to automate processing material through Archivematica
- Deployment: Ansible scripts for deploying and configuring Archivematica
- Deployment-Archivematica: Ansible playbook for Archivematica package install.
- Deployment-Archivematica-dev: Ansible playbook for Archivematica github install.
- Fixity checker: Commandline tool that assists in checking fixity for AIPs stored in Archivematica Storage Service instances.
- METS reader/writer: Library to create and parse METS files.
- agentarchives: Clients to retrieve, add, and modify records from archival management systems.
- Sample data: Data to test and show off Archivematica's processing
- History: Contains the pre-git history of Archivematica. Useful for checking the origins of code.
The recommended way to install Archivematica for development is with Ansible and Vagrant.
Ansible & Vagrant
To install and run Archivematica from source on a VM:
- Checkout deployment repo
git clone https://github.com/artefactual/deploy-pub.git
- Install VirtualBox, Vagrant, Ansible
sudo apt-get install virtualbox vagrant(Ubuntu)
- Vagrant must be at least 1.5 (it can also be downloaded from vagrantup.com)
sudo pip install -U ansible
- Download Ansible roles
ansible-galaxy install -f -r requirements.yml
- (Optional) Change the branch by modifying
- Create virtual machine and provision it
vagrant up(it takes a while)
- Login now available via:
- Services available:
- Provisioning (via ansible) can be re-run with vagrant to update the code on the server
- To re-deploy a new branch to the same VM, update the branch variables in
vars-singlenode.ymllike step 4 described.
- This will probably require resetting the Archivematica installation as well. This can be done by adding variables to
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
- Restart the Archivematica dashboard
sudo /etc/init.d/apache2 startor
sudo service apache2 restart
- Restart the Storage Service
sudo service uwsgi restart
- Restart nginx
sudo service uwsgi restart
sudo service nginx restart
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
See below for project-specific setup or changes to running the tests.
Before running Archivematica tests, set the following environment variable.
#!/usr/bin/fish set -xg PYTHONPATH /usr/share/archivematica/dashboard/:/usr/lib/archivematica/archivematicaCommon/
#!/usr/bin/bash export PYTHONPATH=$PYTHONPATH:/usr/share/archivematica/dashboard/:/usr/lib/archivematica/archivematicaCommon/
Before running Storage Service tests, set the following environment variables
#!/usr/bin/fish set -xg PYTHONPATH (pwd)/storage_service # The project root set -xg DJANGO_SETTINGS_MODULE storage_service.settings.test set -xg DJANGO_SECRET_KEY 'ADDKEY'
#!/usr/bin/bash export PYTHONPATH=$(pwd)/storage_service # The project root export DJANGO_SETTINGS_MODULE=storage_service.settings.test export DJANGO_SECRET_KEY='ADDKEY'