Latest News And Updates - Rad Web Hosting Blog

Learn How to 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. 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. 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 Path A — Install with Docker (recommended) This is the easiest to maintain and aligns with current docs. Install Docker Engine & Compose plugin apt -y install docker.io docker-compose-plugin systemctl enable --now docker Prepare a project directory mkdir -p /opt/archivesspace-docker && cd /opt/archivesspace-docker 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-serverutf8mb4 --collation-serverutf8mb4_unicode_ci environment: MYSQL_ROOT_PASSWORD: "changeMEroot" MYSQL_DATABASE: "archivesspace" MYSQL_USER: "aspace" MYSQL_PASSWORD: "changeMEdb" volumes: - dbdata:/var/lib/mysql healthcheck: test: 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?useraspace&passwordchangeMEdb&useUnicodetrue&characterEncodingUTF-8&useSSLfalse" 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: Launch it docker compose up -d docker compose logs -f archivesspace When healthy: Staff: http://:8080 Public: http://:8081 OAI: http://:8082 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. Path B — Native install (“zip distribution”) Use this if you can’t Dockerize or prefer direct control. Create service account & directories adduser --system --home /opt/archivesspace --group aspace mkdir -p /opt/archivesspace cd /opt/archivesspace 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. 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. 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 Configure config/config.rb Edit /opt/archivesspace/config/config.rb and add (uncomment/append) lines: # Base URLs (adjust hostnames as needed) AppConfig "http://#{Socket.gethostname}:8080" AppConfig "http://#{Socket.gethostname}:8081" AppConfig "http://#{Socket.gethostname}:8082" AppConfig "http://localhost:8090" AppConfig "http://localhost:8091" # MySQL JDBC URL (be sure characterEncoding is UTF-8/utf8) AppConfig "jdbc:mysql://localhost:3306/archivesspace?useraspace&passwordchangeMEdb&useUnicodetrue&characterEncodingUTF-8&useSSLfalse" Primary configuration happens in this file; defaults are commented out. Port defaults are documented as shown above. Initialize the database schema cd /opt/archivesspace sudo -u aspace ./scripts/setup-database.sh The setup script builds tables/indexes against your MySQL DB. Start ArchivesSpace (foreground test) cd /opt/archivesspace sudo -u aspace ./archivesspace.sh start Verify access: Staff: http://:8080 Public: http://:8081 OAI: http://:8082 Create a systemd service /etc/systemd/system/archivesspace.service: DescriptionArchivesSpace service Afternetwork.target mysql.service Wantsmysql.service Typeforking Useraspace Groupaspace WorkingDirectory/opt/archivesspace ExecStart/opt/archivesspace/archivesspace.sh start ExecStop/opt/archivesspace/archivesspace.sh stop Restarton-failure TimeoutSec120 WantedBymulti-user.target Enable & start: systemctl daemon-reload systemctl enable --now archivesspace systemctl status archivesspace Post-install essentials Create the initial admin user Open Staff UI → follow prompts (if shown) to create admin. Then configure repositories, locations, users, groups. Set base URLs if using domains If reverse proxying (below), set AppConfig, , to the public HTTPS URLs you’ll expose. Defaults are fine for internal testing. Email & authentication ArchivesSpace supports pluggable authentication backends. Configure under AppConfig in config.rb if integrating SSO/LDAP/custom. 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. 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 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. Operations 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). 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). Upgrades (safe pattern) Take a DB & data backup. Stop service/containers. 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. Start and watch logs. (“Getting started” docs outline both paths and the project’s release workflow.) 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 useSSLfalse 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. 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 &useSSLfalse in AppConfig 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). 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.

Rad Web Hosting Blog

Recent Posts

Nothing Found

My Feed at https://radwebhosting.com

Services

Categories

Recent Posts

Save on VPS Hosting!

We’re Social!

Rad Web Hosting Blog