Deploying ArchivesSpace

ArchivesSpace is an open-source archives information management application built for archives by archivists. It provides comprehensive tools for managing and providing web access to archives, manuscripts, and digital objects. With support for accessioning, arrangement, description, preservation, and access workflows, ArchivesSpace serves as an essential component of digital infrastructure for libraries, archives, museums, and cultural heritage institutions.

Backed by a robust member community of archivists, librarians, and developers, ArchivesSpace enables organizations to adopt standards, develop shared best practices, and gain intellectual and physical control over their collections. This guide walks you through deploying ArchivesSpace on Klutch.sh using Docker.

Why Choose ArchivesSpace?

Complete Archives Management

Supports accessioning, arrangement, description, preservation, and access functions within a single content management system.

Standards Compliant

Implements archival standards including EAD, MARC21, and DACS for interoperability and best practices.

Community Driven

Active member community contributing to development, documentation, and shared best practices.

Open Source

Free to download and use under the Educational Community License, version 2.0.

Prerequisites

Before deploying ArchivesSpace on Klutch.sh, ensure you have the following:

• A GitHub account for repository hosting
• A Klutch.sh account for deployment
• A MySQL 8.x database (external, managed service recommended)
• A Solr 9.x instance (external, managed service recommended)

External Dependencies Required

ArchivesSpace requires external MySQL and Solr instances for production use. The embedded database is only suitable for testing. You’ll need to provision these services separately before deploying ArchivesSpace.

Architecture Overview

ArchivesSpace consists of multiple components working together:

┌────────────────────────────────────────────────────────────────────┐
│                         ArchivesSpace                               │
├────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Staff UI     │  │ Public UI    │  │ Backend API              │  │
│  │ Port 8080    │  │ Port 8081    │  │ Port 8089                │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐                                │
│  │ OAI-PMH      │  │ Solr Admin   │                                │
│  │ Port 8082    │  │ Port 8090    │                                │
│  └──────────────┘  └──────────────┘                                │
├────────────────────────────────────────────────────────────────────┤
│                    External Dependencies                            │
│  ┌──────────────────────┐     ┌──────────────────────┐             │
│  │       MySQL 8.x      │     │       Solr 9.x       │             │
│  │    (Production DB)   │     │   (Search Index)     │             │
│  └──────────────────────┘     └──────────────────────┘             │
└────────────────────────────────────────────────────────────────────┘

Components

Component	Port	Description
Staff Interface	8080	Administrative interface for archivists
Public Interface	8081	Public-facing discovery interface
Backend API	8089	RESTful API for programmatic access
OAI-PMH Server	8082	Open Archives Initiative Protocol for Metadata Harvesting
Solr Admin	8090	Search index administration console

Creating the Dockerfile

Create a Dockerfile in your project root that uses the official ArchivesSpace image with your custom configuration:

Dockerfile

FROM archivesspace/archivesspace:latest

# Set environment variables
ENV ASPACE_DB_MIGRATE=true
ENV ARCHIVESSPACE_LOGS=/dev/null
ENV TZ=UTC

# Expose all ArchivesSpace ports
EXPOSE 8080 8081 8089 8090 8092

# The base image handles startup
CMD ["/archivesspace/startup.sh"]

Official Image

The archivesspace/archivesspace:latest image is officially maintained by the ArchivesSpace team. It includes Java 17, all required dependencies, and the MySQL connector.

Configuration File

ArchivesSpace uses a Ruby configuration file. Create a config/config.rb file to customize your deployment:

config/config.rb

# ArchivesSpace Configuration
# See: https://docs.archivesspace.org/customization/configuration/

# Database Configuration (MySQL required for production)
# Replace with your actual MySQL connection details
AppConfig[:db_url] = ENV['ASPACE_DB_URL'] || "jdbc:mysql://your-mysql-host:3306/archivesspace?useUnicode=true&characterEncoding=UTF-8&user=archivesspace&password=your-password&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC"

# Solr Configuration
AppConfig[:solr_url] = ENV['ASPACE_SOLR_URL'] || "http://your-solr-host:8983/solr/archivesspace"

# Enable indexing
AppConfig[:enable_solr] = true
AppConfig[:indexer_records_per_thread] = 25

# Session Configuration
AppConfig[:session_expire_after_seconds] = 3600

# Allow any host (configure appropriately for production)
AppConfig[:allowed_hosts] = ['*']

# Public URL Configuration (update with your actual domain)
AppConfig[:public_proxy_url] = ENV['ASPACE_PUBLIC_URL'] || "https://example-app.klutch.sh"
AppConfig[:frontend_proxy_url] = ENV['ASPACE_FRONTEND_URL'] || "https://example-app.klutch.sh/staff"

# OAI-PMH Configuration
AppConfig[:oai_proxy_url] = ENV['ASPACE_OAI_URL'] || "https://example-app.klutch.sh/oai"

# Enable public interface
AppConfig[:enable_public] = true

# PUI (Public User Interface) Settings
AppConfig[:pui_page_actions_print] = true
AppConfig[:pui_page_actions_request] = true

# Branding (customize as needed)
AppConfig[:pui_branding_img] = "/assets/images/archivesspace.small.png"
AppConfig[:pui_branding_img_alt_text] = "ArchivesSpace - Your Institution"

# Timezone
AppConfig[:default_timezone] = "UTC"

Environment Variables

Configure ArchivesSpace through environment variables in the Klutch.sh dashboard:

Required Variables

Variable	Description	Example
ASPACE_DB_URL	Full JDBC MySQL connection URL	jdbc:mysql://host:3306/archivesspace?user=as&password=secret&...
ASPACE_SOLR_URL	Solr instance URL with core name	http://solr-host:8983/solr/archivesspace

Optional Variables

Variable	Description	Default
ASPACE_DB_MIGRATE	Run pending database migrations on startup	true
ASPACE_JAVA_XMX	Maximum Java heap size	-Xmx2048m
ASPACE_PUBLIC_URL	Public interface base URL	None
ASPACE_FRONTEND_URL	Staff interface base URL	None
TZ	Timezone for the application	UTC

Java Configuration

Variable	Description	Default
JAVA_OPTS	Additional Java options	See below
ASPACE_GC_OPTS	Garbage collection options	-XX:+UseG1GC -XX:NewRatio=1

Default JAVA_OPTS:

-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server -Xss1024k -Djavax.accessibility.assistive_technologies=''

Memory Requirements

ArchivesSpace requires at least 1024 MB RAM. For optimal performance with production workloads, allocate at least 2 GB using -Xmx2048m.

Setting Up External Dependencies

MySQL Database

ArchivesSpace requires MySQL 8.x for production use. You can use a managed MySQL service or deploy your own.

Database Requirements:

• MySQL 8.x (or MariaDB 10.4.10 with community support)
• UTF-8 encoding (utf8mb4)
• log_bin_trust_function_creators=1 enabled

Create the database:

CREATE DATABASE archivesspace
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'archivesspace'@'%'
  IDENTIFIED BY 'your-secure-password';

GRANT ALL PRIVILEGES ON archivesspace.*
  TO 'archivesspace'@'%';

FLUSH PRIVILEGES;

Solr Search Index

ArchivesSpace v4.0.0+ requires Solr 9.x for search functionality. The ArchivesSpace team provides a pre-configured Solr Docker image:

archivesspace/solr:latest

If deploying Solr separately, you’ll need to configure it with the ArchivesSpace schema. The configuration files are available in the ArchivesSpace Solr directory.

Project Structure

Your ArchivesSpace deployment repository should have the following structure:

archivesspace-deploy/
├── Dockerfile
├── config/
│   └── config.rb
├── plugins/
│   └── (custom plugins)
├── locales/
│   └── (locale customizations)
└── README.md

Creating a Complete Dockerfile

For a more complete deployment that includes your configuration:

Dockerfile

FROM archivesspace/archivesspace:latest

# Set environment variables
ENV ASPACE_DB_MIGRATE=true \
    ARCHIVESSPACE_LOGS=/dev/null \
    TZ=UTC \
    LANG=C.UTF-8

# Copy custom configuration
COPY config/config.rb /archivesspace/config/config.rb

# Copy any custom plugins (optional)
COPY plugins/ /archivesspace/plugins/

# Copy locale customizations (optional)
COPY locales/ /archivesspace/locales/

# Set proper permissions
USER root
RUN chown -R 1000:1000 /archivesspace/config /archivesspace/plugins /archivesspace/locales
USER 1000:1000

# Expose all ArchivesSpace ports
EXPOSE 8080 8081 8089 8090 8092

# Health check
HEALTHCHECK --interval=1m --timeout=5s --start-period=5m --retries=2 \
  CMD wget -q --spider http://localhost:8089/ || exit 1

CMD ["/archivesspace/startup.sh"]

Deploying to Klutch.sh

1. Set up external dependencies first

   Before deploying ArchivesSpace, ensure your MySQL database and Solr instance are running and accessible:

   • Create your MySQL database with the required settings
   • Deploy and configure your Solr instance with the ArchivesSpace schema
   • Note the connection URLs for both services

2. Push your repository to GitHub

   Create a new repository on GitHub and push your configuration:

   git init
   git add .
   git commit -m "Initial ArchivesSpace deployment configuration"
   git branch -M main
   git remote add origin https://github.com/yourusername/archivesspace-deploy.git
   git push -u origin main

3. Connect to Klutch.sh

   Navigate to klutch.sh/app and sign in with your GitHub account. Click New Project to begin the deployment process.

4. Select your repository

   Choose the GitHub repository containing your ArchivesSpace Dockerfile. Klutch.sh will automatically detect the Dockerfile in your project root.

5. Configure environment variables

   Add the required environment variables in the Klutch.sh dashboard:

   • ASPACE_DB_URL - Your full MySQL JDBC connection URL
   • ASPACE_SOLR_URL - Your Solr instance URL with core name
   • ASPACE_DB_MIGRATE - Set to true
   • ASPACE_JAVA_XMX - Set to -Xmx2048m for production
   • TZ - Your preferred timezone (e.g., America/New_York)

6. Set the internal port

   Configure the internal port to 8080 for the staff interface, or 8081 for the public interface, depending on which interface you want to expose as the primary endpoint.

   Multiple Interfaces

   ArchivesSpace exposes multiple interfaces on different ports. For a single deployment, you’ll typically expose either the staff interface (8080) or the public interface (8081). For full functionality, consider deploying separate instances or using a reverse proxy.

7. Add persistent storage

   ArchivesSpace requires persistent storage for application data. Add a persistent volume:

   Mount Path	Size
   /archivesspace/data	5 GB+

8. Deploy your application

   Click Deploy to start the deployment process. The first startup may take several minutes as ArchivesSpace initializes the database schema and runs any pending migrations.

First-Time Setup

After deployment, complete the initial configuration:

1. Access the Staff Interface

   Navigate to your deployed ArchivesSpace URL (e.g., https://example-app.klutch.sh). You should see the staff login page.

2. Log in with default credentials

   Use the default administrator account:

   • Username: admin
   • Password: admin

   Change Default Password

   Immediately change the default admin password after your first login! Navigate to System → Manage Users → admin → Edit to update the password.

3. Create your first repository

   From the System menu, select Manage Repositories and create your first archival repository.

4. Configure user accounts

   Create additional user accounts with appropriate permissions for your staff members.

ArchivesSpace Features

Staff Interface Functions

The staff interface (port 8080) provides tools for:

• Accessions: Record incoming materials
• Resources: Create and manage finding aids (EAD)
• Archival Objects: Describe components within collections
• Digital Objects: Manage digital materials and links
• Agents: Authority records for people, organizations, families
• Subjects: Subject headings and controlled vocabularies
• Assessments: Evaluate collections for processing priorities
• Jobs: Background processing and batch operations

Public Interface Features

The public interface (port 8081) offers:

• Discovery: Search and browse collections
• Finding Aids: View detailed collection descriptions
• Digital Object Access: Access digital materials
• Request System: Submit reference requests
• Export Options: Download finding aids in various formats

API Access

The backend API (port 8089) enables:

• Programmatic access to all ArchivesSpace data
• Integration with other systems
• Batch data operations
• Custom reporting and exports

Configuration Options

Customizing the Public Interface

Edit config/config.rb to customize the public interface:

# Institution branding
AppConfig[:pui_branding_img] = "/assets/images/your-logo.png"
AppConfig[:pui_branding_img_alt_text] = "Your Institution Name"

# Page titles
AppConfig[:pui_page_title] = "Your Archives"

# Contact information
AppConfig[:pui_email] = "archives@yourinstitution.org"
AppConfig[:pui_telephone] = "555-123-4567"

# Enable/disable features
AppConfig[:pui_page_actions_print] = true
AppConfig[:pui_page_actions_request] = true
AppConfig[:pui_page_actions_cite] = true

Adding Plugins

ArchivesSpace supports plugins for extended functionality. Place plugin directories in the plugins/ folder and enable them in config/config.rb:

# Enable plugins
AppConfig[:plugins] = ['local', 'lcnaf', 'your_custom_plugin']

Popular plugins include:

• lcnaf - Library of Congress Name Authority File integration
• aspace-oauth - OAuth authentication
• Various import/export plugins

Locale Customizations

Customize interface text by adding locale files to the locales/ directory:

locales/en.yml

en:
  brand:
    title: "Your Institution Archives"
    welcome_message: "Welcome to our archival collections"

Custom Domain Setup

To use a custom domain with your ArchivesSpace deployment:

1. Add your domain in Klutch.sh

   Navigate to your project settings in the Klutch.sh dashboard and add your custom domain (e.g., archives.yourinstitution.org).

2. Configure DNS records

   Add a CNAME record pointing to your Klutch.sh deployment:

   Type	Name	Value
   CNAME	archives	example-app.klutch.sh

3. Update configuration URLs

   Update the proxy URLs in your config/config.rb or environment variables:

   AppConfig[:public_proxy_url] = "https://archives.yourinstitution.org"
   AppConfig[:frontend_proxy_url] = "https://archives.yourinstitution.org/staff"

4. Wait for SSL provisioning

   Klutch.sh automatically provisions SSL certificates for custom domains. This may take a few minutes.

Local Development with Docker Compose

For local development and testing:

docker-compose.yml

services:
  archivesspace:
    image: archivesspace/archivesspace:latest
    depends_on:
      - db
      - solr
    ports:
      - "8080:8080"  # Staff interface
      - "8081:8081"  # Public interface
      - "8089:8089"  # API
    volumes:
      - app-data:/archivesspace/data
      - ./config:/archivesspace/config
      - ./plugins:/archivesspace/plugins
    environment:
      - ASPACE_DB_MIGRATE=true
      - ASPACE_JAVA_XMX=-Xmx2048m

  db:
    image: mysql:8
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --log_bin_trust_function_creators=1
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=archivesspace
      - MYSQL_USER=archivesspace
      - MYSQL_PASSWORD=archivesspace
    volumes:
      - db-data:/var/lib/mysql

  solr:
    image: archivesspace/solr:latest
    command: solr-precreate archivesspace /opt/solr/server/solr/configsets/archivesspace
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/var/solr

volumes:
  app-data:
  db-data:
  solr-data:

Start the local environment:

docker compose up -d

Wait for initialization (first startup may take 5-10 minutes), then access:

• Staff Interface: http://localhost:8080 (admin/admin)
• Public Interface: http://localhost:8081
• API: http://localhost:8089
• Solr Admin: http://localhost:8983

Troubleshooting

Database Connection Issues

If ArchivesSpace fails to connect to MySQL:

1. Verify your MySQL connection URL format:

   jdbc:mysql://host:3306/database?useUnicode=true&characterEncoding=UTF-8&user=username&password=password&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC

2. Ensure log_bin_trust_function_creators=1 is set in MySQL

3. Check that the database user has full privileges on the ArchivesSpace database

Solr Connection Issues

If search isn’t working:

1. Verify Solr is running and accessible
2. Check that the ArchivesSpace schema is loaded in your Solr core
3. Ensure the ASPACE_SOLR_URL includes the core name (e.g., /solr/archivesspace)

Slow Startup

Initial startup can take several minutes as ArchivesSpace:

• Initializes the database schema
• Runs pending migrations
• Builds the Solr index

Monitor logs for the welcome message indicating successful startup.

Memory Issues

If experiencing out-of-memory errors:

• Increase ASPACE_JAVA_XMX to -Xmx3072m or higher
• Ensure your Klutch.sh deployment has adequate resources

Resources

• ArchivesSpace GitHub Repository
• Technical Documentation
• API Reference
• ArchivesSpace Website
• Wiki Documentation

Next Steps

After deploying ArchivesSpace, consider:

• Joining the ArchivesSpace member community for support and resources
• Exploring plugins for additional functionality
• Setting up automated database backups
• Configuring LDAP or OAuth for institutional authentication
• Customizing the public interface for your institution’s branding
• Training staff on ArchivesSpace workflows
• Planning for data migration from existing systems