Manually Installing Archivematica on Ubuntu¶

Ubuntu 22.04 (Jammy) installation instructions¶

1. Use these commands to install the repositories:

   curl -fsSL https://packages.archivematica.org/1.17.x/key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/archivematica-1.17.x.gpg
   
   sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/archivematica-1.17.x.gpg] http://packages.archivematica.org/1.17.x/ubuntu jammy main" > /etc/apt/sources.list.d/archivematica.list'
   sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/archivematica-1.17.x.gpg] http://packages.archivematica.org/1.17.x/ubuntu-externals jammy main" > /etc/apt/sources.list.d/archivematica-externals.list'
   

2. Add Elasticsearch package source (optional). Elasticsearch comes from its own package repository.

   Note

   Skip this step if you are planning to run Archivematica without Elasticsearch.

   curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /etc/apt/keyrings/elasticsearch-6.x.gpg
   echo "deb [signed-by=/etc/apt/keyrings/elasticsearch-6.x.gpg] https://artifacts.elastic.co/packages/6.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-6.x.list
   

3. Update to the most recent OS release. This step will also fetch a list of the software from the package repositories you just added to your system.

   sudo apt-get update
   sudo apt-get -y upgrade
   

4. Install some needed packages

   sudo apt-get install -y openjdk-8-jre-headless mysql-server
   

5. Install Elasticsearch (optional)

   Note

   Skip this step if you are planning to run Archivematica in indexless mode (without Elasticsearch).

   sudo apt-get install -y elasticsearch
   

6. Now that MySQL is up and running, install the Storage Service. You will be prompted to create a password for its database. If necessary, the password can be changed after the installation is complete.

   sudo apt-get install -y archivematica-storage-service
   

7. Configure the Storage Service.

   sudo rm -f /etc/nginx/sites-enabled/default
   sudo ln -sf /etc/nginx/sites-available/storage /etc/nginx/sites-enabled/storage
   

8. Install the Archivematica packages. The order of installation is important - the archivematica-mcp-server package must be installed before the dashboard package. While it is possible to install the archivematica-mcp-client package on a separate machine, that configuration is not documented in these instructions.

   The archivematica-mcp-server package will install MySQL and configure the database used by Archivematica. Depending on the version of MySQL that is installed, the interfaces that you see may differ slightly.

   You will be prompted to create a password for the database. If necessary, the password can be changed after the installation is complete.

   sudo apt-get install -y archivematica-mcp-server
   sudo apt-get install -y archivematica-dashboard
   sudo apt-get install -y archivematica-mcp-client
   

9. Configure the Archivematica components (optional). There are a number of environment variables that Archivematica recognizes which can be used to alter how it is configured. For the full list, see the Dashboard install README, the MCPClient install README, and the MCPServer install README.

   Note

   If you are planning on running Archivematica in indexless mode (i.e. without Elasticsearch), then modify the relevant systemd EnvironmentFile files by adding lines that set the relevant environment variables to false:

   sudo sh -c 'echo "ARCHIVEMATICA_DASHBOARD_DASHBOARD_SEARCH_ENABLED=false" >> /etc/default/archivematica-dashboard'
   sudo sh -c 'echo "ARCHIVEMATICA_MCPSERVER_MCPSERVER_SEARCH_ENABLED=false" >> /etc/default/archivematica-mcp-server'
   sudo sh -c 'echo "ARCHIVEMATICA_MCPCLIENT_MCPCLIENT_SEARCH_ENABLED=false" >> /etc/default/archivematica-mcp-client'
   

10. Configure the dashboard.

    sudo ln -sf /etc/nginx/sites-available/dashboard.conf /etc/nginx/sites-enabled/dashboard.conf
    

11. Start Elasticsearch (optional).

    Note

    Skip this step if you are planning to run Archivematica in indexless mode (without Elasticsearch).

    sudo systemctl daemon-reload
    sudo service elasticsearch restart
    sudo systemctl enable elasticsearch
    

12. Start the remaining services

    sudo service clamav-freshclam restart
    sleep 120s
    sudo service clamav-daemon start
    sudo service gearman-job-server restart
    sudo service archivematica-mcp-server start
    sudo service archivematica-mcp-client restart
    sudo service archivematica-storage-service start
    sudo service archivematica-dashboard restart
    sudo service nginx restart
    
    sudo ufw allow 22/tcp
    

    If you have trouble with the gearman or clamav command try restarting it:

    sudo service gearman-job-server restart
    sudo service clamav-daemon restart
    

13. Configure your firewall (if applicable)

    On Ubuntu, the default firewall configuration tool is ufw (Uncomplicated Firewall). To see the firewall status, enter:

    sudo ufw status
    

    If ufw is active, you must ensure that it is not blocking the ports used by the dashboard and the Storage Service, i.e., 80 and 8000.

    sudo ufw reload
    
    sudo -u archivematica bash -c " \
    

14. Complete Post Install Configuration.

Post-install configuration¶

After successfully completing a new installation, follow these steps to complete the configuration of your new server.

1. The Storage Service runs as a separate web application from the Archivematica dashboard. The Storage Service is exposed on port 8000 by default for Ubuntu package installs. Use your web browser to navigate to the Storage Service at the IP address of the machine you have been installing on, e.g., http://<MY-IP-ADDR>:8000 (or http://localhost:8000 or http://127.0.0.1:8000 if this is a local development setup).

   If you are using an IP address or fully-qualified domain name instead of localhost, you will need to configure your firewall rules and allow access only to ports 80 and 8000 for Archivematica usage.

2. The Storage Service has its own set of users. Add at least one administrative user:

   sudo -u archivematica bash -c " \
       set -a -e -x
       source /etc/default/archivematica-storage-service || \
           source /etc/sysconfig/archivematica-storage-service \
               || (echo 'Environment file not found'; exit 1)
       cd /usr/lib/archivematica/storage-service
       /usr/share/archivematica/virtualenvs/archivematica-storage-service/bin/python manage.py createsuperuser
       ";
   

   After you have created this user an API key will be generated that will connect the Archivematica pipeline to the Storage Service API. Click edit to see the new user’s details. The API key will be found at the bottom of the page. Copy this to your clipboard as it will be used later on in the post-installation configuration.

   Note

   It is recommended that you also modify the test user and change the default password. This will also result in a new API key for the test user but that does not need to be copied to the clipboard in this instance.

3. To finish the installation, use your web browser to navigate to the Archivematica dashboard using the IP address of the machine on which you have been installing, e.g., http://<MY-IP-ADDR>:80 (or http://localhost:80 or http://127.0.0.1:80 if this is a local development setup).

4. At the Welcome page, create an administrative user for the Archivematica pipeline by entering the organization name, the organization identifier, username, email, and password.

5. On the next screen, connect your pipeline to the Storage Service by entering the Storage Service URL and username, and by pasting in the API key that you copied in Step (2).

   • If the Storage Service and the Archivematica dashboard are installed on the same machine, then you should supply http://127.0.0.1:8000 as the Storage Service URL at this screen.
   • If the Storage Service and the Archivematica dashboard are installed on different nodes (servers), then you should use the IP address or fully-qualified domain name of your Storage Service instance, e.g., http://<MY-IP-ADDR>:8000 and you must ensure that any firewall rules (i.e., iptables, ufw, AWS security groups, etc.) are configured to allow requests from your dashboard IP to your Storage Service IP on the appropriate port.

Back to the top