Install and Run ArchivesSpace on Ubuntu VPS

This article provides a guide to install and run ArchivesSpace on Ubuntu VPS.

What is ArchivesSpace?

ArchivesSpace is an open-source, web-based archives information management application. It’s widely used by libraries, museums, universities, and cultural heritage institutions to manage and provide access to archival collections.

Here are the key points:

Purpose

• Helps archivists describe, manage, and publish finding aids for archival materials.
• Serves as a centralized system for collection management, replacing older tools like Archivists’ Toolkit and Archon.

Features

• Collection management: Organize materials hierarchically (collections, series, files, items).
• Standards-compliant: Supports archival description standards such as EAD (Encoded Archival Description), MARCXML, Dublin Core, and METS.
• Public interface: Offers a discovery portal so researchers and the public can search collections.
• Multi-user environment: Role-based access for archivists, staff, and administrators.
• Integration: APIs and plugins allow connection to other systems (e.g., library catalogs, digital repositories).

Community & Development

• Supported by the Lyrasis consortium with contributions from a global community of archivists and developers.
• Open-source and customizable to meet the needs of different organizations.

In short, ArchivesSpace is like a specialized database and publishing platform for archival collections, making it easier for institutions to manage and share their historical records.

Compare Ubuntu VPS Plans

How to Install and Run ArchivesSpace on Ubuntu VPS

Here’s a complete, production-oriented guide to install and run ArchivesSpace (often misspelled “ArchiveSpace”) on an Ubuntu VPS. It covers two supported paths—the Docker method (recommended by the project for new installs) and a native “zip distribution” install—plus hardening, reverse proxy, systemd, backup/restore, and upgrades.

Tested on Ubuntu 22.04/Ubuntu 24.04. Replace example passwords/domains to fit your environment.

1. Quick facts you’ll need

   • Components & ports (defaults):
   • Staff UI: :8080
   • Public UI (PUI): :8081
   • OAI-PMH: :8082
   • Solr (embedded): :8090
   • Indexer: :8091
   • Database: Use MySQL 5.x or 8.x for production (embedded DB is for demos). You must add MySQL Connector/J jar under archivesspace/lib.
   • Config file: archivesspace/config/config.rb drives almost everything (URLs, ports, DB, auth).
   • Project docs: Start with “Getting started,” which now emphasizes Docker or the zip distribution.

2. Prerequisites (both paths)

   # Become root or prefix with sudo
   apt update && apt -y upgrade
   
   # Basic tools
   apt -y install curl unzip git ufw
   
   # (Optional) OpenJDK if building plugins/tools; runtime is bundled by ASpace, but JRE is listed in reqs
   apt -y install openjdk-17-jre-headless
   

   ArchivesSpace tech docs list Java runtime among software requirements; modern builds bundle what’s needed, but OpenJDK doesn’t hurt if you extend.

   Harden SSH/firewall (example allowing SSH + HTTP/HTTPS):

   ufw allow OpenSSH
   ufw allow http
   ufw allow https
   ufw enable
   

3. Path A — Install with Docker (recommended)

   This is the easiest to maintain and aligns with current docs.

   1. Install Docker Engine & Compose plugin

      apt -y install docker.io docker-compose-plugin
      systemctl enable --now docker
      

   2. Prepare a project directory

      mkdir -p /opt/archivesspace-docker && cd /opt/archivesspace-docker
      

   3. Create a docker-compose.yml

      The project provides official guidance to run ArchivesSpace + MySQL + Solr via Docker for development and deployment. Below is a production-style compose tailored for a single host.

      services:
        db:
          image: mysql:8.0
          command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
          environment:
            MYSQL_ROOT_PASSWORD: "changeMEroot"
            MYSQL_DATABASE: "archivesspace"
            MYSQL_USER: "aspace"
            MYSQL_PASSWORD: "changeMEdb"
          volumes:
            - dbdata:/var/lib/mysql
          healthcheck:
            test: ["CMD", "mysqladmin", "ping", "-pchangeMEroot"]
            interval: 10s
            retries: 10
          restart: unless-stopped
      
        archivesspace:
          image: archivesspace/archivesspace:latest
          depends_on:
            db:
              condition: service_healthy
          environment:
            ASPACE_DB_URL: "jdbc:mysql://db:3306/archivesspace?user=aspace&password=changeMEdb&useUnicode=true&characterEncoding=UTF-8&useSSL=false"
            ASPACE_PUBLIC_URL: "http://aspace.example.org:8081"
            ASPACE_FRONTEND_URL: "http://aspace.example.org:8080"
            ASPACE_OAI_URL: "http://aspace.example.org:8082"
          ports:
            - "8080:8080"  # staff
            - "8081:8081"  # public
            - "8082:8082"  # oai
          volumes:
            - aspace-data:/archivesspace/data
            - aspace-plugins:/archivesspace/plugins
            - aspace-config:/archivesspace/config
          restart: unless-stopped
      
      volumes:
        dbdata:
        aspace-data:
        aspace-plugins:
        aspace-config:
      

   4. Launch it

      docker compose up -d
      docker compose logs -f archivesspace
      

      When healthy:

      • Staff: http://:8080
      • Public: http://:8081
      • OAI: http://:8082

   5. First-run tasks

      • Create admin user in Staff UI if prompted.
      • Configure repositories, locations, agents.
      • Plan to put Nginx in front with HTTPS (see section 6). Project docs describe HTTPS patterns.

4. Path B — Native install (“zip distribution”)

   Use this if you can’t Dockerize or prefer direct control.

   1. Create service account & directories

      adduser --system --home /opt/archivesspace --group aspace
      mkdir -p /opt/archivesspace
      cd /opt/archivesspace
      

   2. Download & unpack ArchivesSpace

      Get the latest release zip from the project site and extract to /opt/archivesspace. (Use the current version filename.)

      curl -L -o /tmp/archivesspace.zip https://github.com/archivesspace/archivesspace/releases/latest/download/archivesspace.zip
      unzip /tmp/archivesspace.zip -d /opt
      mv /opt/archivesspace* /opt/archivesspace
      chown -R aspace:aspace /opt/archivesspace
      

      The distribution contains the apps (backend, staff, public), Solr, and scripts.

   3. Install MySQL 8 and create DB/user

      apt -y install mysql-server
      mysql -uroot <<'SQL'
      CREATE DATABASE archivesspace CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
      CREATE USER 'aspace'@'localhost' IDENTIFIED BY 'changeMEdb';
      GRANT ALL PRIVILEGES ON archivesspace.* TO 'aspace'@'localhost';
      FLUSH PRIVILEGES;
      SQL
      

      ArchivesSpace recommends MySQL (5.x or 8.x) for production. Use UTF-8/utf8mb4.

   4. Add MySQL Connector/J to the classpath

      Required because licensing prevents bundling; place the jar in archivesspace/lib.

      cd /opt/archivesspace/lib
      curl -O https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.0.33/mysql-connector-j-8.0.33.jar
      chown aspace:aspace mysql-connector-j-8.0.33.jar
      

   5. Configure config/config.rb

      Edit /opt/archivesspace/config/config.rb and add (uncomment/append) lines:

      # Base URLs (adjust hostnames as needed)
      AppConfig[:frontend_url] = "http://#{Socket.gethostname}:8080"
      AppConfig[:public_url]   = "http://#{Socket.gethostname}:8081"
      AppConfig[:oai_url]      = "http://#{Socket.gethostname}:8082"
      AppConfig[:solr_url]     = "http://localhost:8090"
      AppConfig[:indexer_url]  = "http://localhost:8091"
      
      # MySQL JDBC URL (be sure characterEncoding is UTF-8/utf8)
      AppConfig[:db_url] = "jdbc:mysql://localhost:3306/archivesspace?user=aspace&password=changeMEdb&useUnicode=true&characterEncoding=UTF-8&useSSL=false"
      

      Primary configuration happens in this file; defaults are commented out.
      Port defaults are documented as shown above.

   6. Initialize the database schema

      cd /opt/archivesspace
      sudo -u aspace ./scripts/setup-database.sh
      

      The setup script builds tables/indexes against your MySQL DB.

   7. Start ArchivesSpace (foreground test)

      cd /opt/archivesspace
      sudo -u aspace ./archivesspace.sh start
      

      Verify access:

      • Staff: http://:8080
      • Public: http://:8081
      • OAI: http://:8082

   8. Create a systemd service

      /etc/systemd/system/archivesspace.service:

      [Unit]
      Description=ArchivesSpace service
      After=network.target mysql.service
      Wants=mysql.service
      
      [Service]
      Type=forking
      User=aspace
      Group=aspace
      WorkingDirectory=/opt/archivesspace
      ExecStart=/opt/archivesspace/archivesspace.sh start
      ExecStop=/opt/archivesspace/archivesspace.sh stop
      Restart=on-failure
      TimeoutSec=120
      
      [Install]
      WantedBy=multi-user.target
      

      Enable & start:

      systemctl daemon-reload
      systemctl enable --now archivesspace
      systemctl status archivesspace
      

5. Post-install essentials

   1. Create the initial admin user

      Open Staff UI → follow prompts (if shown) to create admin. Then configure repositories, locations, users, groups.

   2. Set base URLs if using domains

      If reverse proxying (below), set AppConfig[:frontend_url], [:public_url], [:oai_url] to the public HTTPS URLs you’ll expose. Defaults are fine for internal testing.

   3. Email & authentication

      ArchivesSpace supports pluggable authentication backends. Configure under AppConfig[:authentication_sources] in config.rb if integrating SSO/LDAP/custom.

6. Put Nginx in front with HTTPS (recommended)

   The project documents approaches to serve end-user URLs over HTTPS. Use a standard Nginx reverse proxy + Let’s Encrypt.

   1. Install & get a cert

      apt -y install nginx certbot python3-certbot-nginx
      certbot --nginx -d aspace.example.org -m you@example.org --agree-tos --no-eff-email
      

   2. Nginx site (staff + public on one hostname with paths)

      /etc/nginx/sites-available/archivesspace.conf:

      server {
        listen 80;
        server_name aspace.example.org;
        return 301 https://$host$request_uri;
      }
      
      server {
        listen 443 ssl http2;
        server_name aspace.example.org;
      
        ssl_certificate     /etc/letsencrypt/live/aspace.example.org/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/aspace.example.org/privkey.pem;
      
        # Public UI
        location / {
          proxy_pass http://127.0.0.1:8081;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-Proto https;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
      
        # Staff UI (optional: protect by IP/VPN)
        location /staff/ {
          rewrite ^/staff/(.*)$ /$1 break;
          proxy_pass http://127.0.0.1:8080;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-Proto https;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
      
        # OAI-PMH (optional)
        location /oai {
          proxy_pass http://127.0.0.1:8082;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-Proto https;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
      }
      

      Enable & reload:

      ln -s /etc/nginx/sites-available/archivesspace.conf /etc/nginx/sites-enabled/
      nginx -t && systemctl reload nginx
      

      Update config.rb URLs to your HTTPS endpoints (e.g., https://aspace.example.org, https://aspace.example.org/staff/, https://aspace.example.org/oai) and restart ArchivesSpace.

7. Operations

   1. Service control & logs

      # Native
      systemctl status|start|stop|restart archivesspace
      journalctl -u archivesspace -f
      
      # Docker
      docker compose ps
      docker compose logs -f archivesspace
      

      Useful log locations (native): /opt/archivesspace/logs/ (backend, indexer, solr).

   2. Backups

      • MySQL:

        mysqldump -u root -p --single-transaction --routines --triggers archivesspace | gzip > /backup/archivesspace_$(date +%F).sql.gz
        

      • Data & config:
        Back up /opt/archivesspace/data and /opt/archivesspace/config (native) or the equivalent Docker volumes (aspace-data, aspace-config).
      • Restore: mysql < dump.sql, then restore data/config. Rebuild the index if needed (restart triggers reindexing).

   3. Upgrades (safe pattern)

      1. Take a DB & data backup.
      2. Stop service/containers.
      3. Docker: change image tag (e.g., :latest → specific version) and docker compose up -d.
         Native: download new zip, stop service, replace /opt/archivesspace (keep a copy of your config/ and plugins/), re-run scripts/setup-database.sh if release notes require schema upgrades.
      4. Start and watch logs.
         (“Getting started” docs outline both paths and the project’s release workflow.)

8. Tuning & Production Tips

   • Memory/CPU: Ensure enough RAM/CPU for Solr + indexer; small sites run with 2–4 GB, but more helps. (Docs call out memory needs in system requirements.)
   • MySQL 8 quirks: Some deployments add useSSL=false and ensure user auth plugin compatibility.
   • Character set: Always use utf8mb4 for full Unicode.
   • Indexer/Solr ports: If you move them, update :solr_url and :indexer_url accordingly.
   • Public UI (PUI): Enabled and served by default on :8081; customize via config.rb and theme/plugins as needed.
   • HTTPS everywhere: Terminate TLS at Nginx; update config.rb URLs to your HTTPS endpoints to avoid mixed-content and redirect oddities.

9. Troubleshooting

   • “DB connection failed: com.mysql.jdbc.Driver not loaded”
     You’re missing MySQL Connector/J jar in archivesspace/lib, or wrong version. Add the current mysql-connector-j-.jar and restart.
   • MySQL 8 auth/SSL issues
     Try &useSSL=false in AppConfig[:db_url] and ensure the MySQL user uses a compatible auth plugin.
   • Ports already in use
     Change the app ports in config.rb (8080/8081/8082/8090/8091) or free the conflicting service.
   • Admin/login not visible in PUI
     That’s expected. Staff UI is on 8080; PUI is public browse/search (no staff features).

10. Where to go next

    • Getting started (official): install paths, requirements, and first steps.
    • Configuration reference: full config.rb options.
    • MySQL provisioning guide: connector/J, DB URL, setup-database script.
    • HTTPS deployment patterns: reverse proxy guidance.
    • Clustering/advanced provisioning: multi-tenant/multi-host notes (for growth).

Conclusion

You now know how to install and run ArchivesSpace on Ubuntu VPS.

Compare Ubuntu VPS Plans