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.

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
      # or run in foreground to see logs:
      sudo -u aspace ./archivesspace.sh run
      

      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.