Deploying EPrints

Introduction

EPrints is a leading open-source institutional repository software platform designed for academic institutions, research organizations, and libraries to store, manage, and provide access to digital research outputs. Developed at the University of Southampton, EPrints has powered thousands of repositories worldwide for over two decades, making research publications, theses, datasets, and multimedia freely accessible while ensuring long-term preservation.

At its core, EPrints provides a robust framework for collecting, organizing, and disseminating scholarly work. The platform supports diverse content types including journal articles, conference papers, book chapters, technical reports, theses, datasets, audio, video, and even 3D models. Each item is described with rich metadata following standards like Dublin Core, enabling powerful search and discovery capabilities across institutional repositories.

EPrints excels at:

Open Access Publishing: Facilitate institutional mandates for open access by providing immediate, unrestricted access to research outputs
Research Information Management: Track publications, grants, impact metrics, and researcher profiles in a unified system
Metadata Standards: Full support for Dublin Core, OAI-PMH harvesting, SWORD deposits, and ORCID integration
Flexible Workflows: Configurable submission workflows with mediation, peer review, and quality control stages
Preservation: Long-term digital preservation with version control, checksums, and format migration capabilities
Customizable Views: Create multiple website views, RSS feeds, and data exports tailored to different audiences
Full-Text Indexing: Powerful search across document content, metadata, and references
Access Control: Granular permissions for viewing, downloading, and editing based on user roles
Usage Statistics: Comprehensive analytics on downloads, views, and research impact
Extensibility: Plugin architecture and Perl-based customization for specialized institutional needs

The platform is particularly strong in academic contexts where research visibility, compliance with funder mandates, and bibliographic accuracy are critical. EPrints automatically extracts metadata, generates citations in hundreds of formats, enables batch imports from reference managers, and integrates with external systems like Crossref, PubMed, and institutional authentication services.

This comprehensive guide walks you through deploying EPrints on Klutch.sh using Docker, connecting to a MySQL database, configuring persistent storage for research archives, and setting up production-ready institutional repositories that comply with global open access standards.

Why Deploy EPrints on Klutch.sh

Deploying EPrints on Klutch.sh provides several advantages for academic and research institutions:

Automated Docker Detection: Klutch.sh automatically detects your Dockerfile and builds your EPrints container with all Perl dependencies, Apache configuration, and database drivers pre-configured
Persistent Volume Support: Attach persistent storage for EPrints’ archive directory, ensuring research outputs, documents, and metadata survive container restarts and platform updates
Database Flexibility: Connect to managed MySQL/MariaDB instances deployed on Klutch.sh or external databases, with environment variables for secure credential management
HTTPS by Default: All EPrints repositories get automatic HTTPS encryption, ensuring secure access to sensitive research data and protecting researcher privacy
Scalable Architecture: Start with a single repository and scale resources as your collection grows, handling millions of research objects and concurrent users
GitHub Integration: Version control your EPrints configuration, custom plugins, and site templates in GitHub with automatic redeployment on code changes
Zero Infrastructure Management: No need to manage Linux servers, Apache configuration, or Perl module installations—focus on repository management and researcher support
Custom Domain Support: Point institutional domains to your EPrints repository for professional branding and improved discoverability
Environment Variable Management: Securely store database credentials, admin passwords, and API keys without hardcoding them in configuration files
Cost-Effective Hosting: Pay only for the resources you use, with flexible scaling during peak submission periods or harvest operations

Prerequisites

Before deploying EPrints on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account for hosting your EPrints configuration repository
A MySQL or MariaDB database (follow our MySQL deployment guide to set one up on Klutch.sh)
Basic understanding of institutional repositories and scholarly communication
Familiarity with Docker and containerization concepts
(Optional) Knowledge of Perl for customization and plugin development
(Optional) Understanding of metadata standards like Dublin Core and OAI-PMH

Understanding EPrints Architecture

EPrints follows a classic web application architecture with several interconnected components:

Application Layer (Perl/Apache):

EPrints core is written in Perl and runs on Apache with mod_perl for performance
The platform uses object-oriented design with a flexible plugin architecture
Custom workflows, data models, and site behavior are defined in Perl configuration files

Database Layer (MySQL/MariaDB):

All metadata, user accounts, workflows, and repository configuration are stored in MySQL
The database schema uses a table-per-dataset model for flexibility
Full-text search can use MySQL’s built-in indexing or be offloaded to Xapian

Storage Layer (File System):

Research documents, images, videos, and other files are stored in a hierarchical archive directory
Each item (eprint) gets a unique ID with corresponding filesystem directory
Files are organized by dataset, ID, and version for efficient retrieval and preservation

Web Interface:

EPrints generates dynamic HTML pages using a template-based system
The platform provides separate interfaces for public access, depositors, editors, and administrators
Views are highly customizable through template files and CSS styling

Indexing and Search:

Default indexing uses MySQL full-text search for metadata
Optional Xapian integration provides faster, more sophisticated full-text search of document content
OAI-PMH endpoint exposes metadata for harvesting by aggregators

Background Processing:

A cron-based indexer runs periodically to update search indexes
Document format conversion, thumbnail generation, and metadata extraction happen asynchronously
Email notifications for workflow events are queued and processed in batches

Preparing Your Repository

To deploy EPrints on Klutch.sh, you’ll create a GitHub repository with a Dockerfile that configures EPrints with all necessary dependencies.

Step 1: Create Your Project Directory

Start by creating a local directory for your EPrints project:

mkdir eprints-klutch
cd eprints-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root. This example builds EPrints 3.4 with all required Perl modules and Apache configuration:

FROM ubuntu:22.04

# Avoid interactive prompts during package installation
ENV DEBIAN_FRONTEND=noninteractive

# Set EPrints version
ENV EPRINTS_VERSION=3.4.5

# Install system dependencies
RUN apt-get update && apt-get install -y \
    apache2 \
    cpanminus \
    curl \
    gcc \
    git \
    libapache2-mod-perl2 \
    libapache2-reload-perl \
    libarchive-zip-perl \
    libcgi-pm-perl \
    libdbd-mysql-perl \
    libdbi-perl \
    libemail-mime-perl \
    libgd-dev \
    libgd-perl \
    libio-socket-ssl-perl \
    libjson-perl \
    liblingua-stem-perl \
    libmime-lite-perl \
    libpod-latex-perl \
    libterm-readkey-perl \
    libtext-unidecode-perl \
    libtime-hires-perl \
    libunicode-string-perl \
    liburi-perl \
    libwww-perl \
    libxml-libxml-perl \
    libxml-libxslt-perl \
    libxml-parser-perl \
    libxml-sax-perl \
    libxml-simple-perl \
    make \
    mysql-client \
    perl \
    perl-doc \
    sudo \
    wget \
    && rm -rf /var/lib/apt/lists/*

# Install additional Perl modules via CPAN
RUN cpanm --notest \
    CGI::Cookie \
    Data::Dumper \
    Digest::MD5 \
    File::Copy \
    File::Path \
    MIME::Base64 \
    Sys::Hostname \
    Text::Wrap \
    Time::Local

# Create EPrints user
RUN useradd -m -s /bin/bash eprints && \
    echo "eprints ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# Set working directory
WORKDIR /opt

# Download and extract EPrints
RUN wget https://github.com/eprints/eprints3.4/archive/refs/tags/v${EPRINTS_VERSION}.tar.gz && \
    tar -xzf v${EPRINTS_VERSION}.tar.gz && \
    mv eprints3.4-${EPRINTS_VERSION} eprints3 && \
    rm v${EPRINTS_VERSION}.tar.gz

# Set ownership
RUN chown -R eprints:eprints /opt/eprints3

# Create archive directory
RUN mkdir -p /opt/eprints3/archives && \
    chown -R eprints:eprints /opt/eprints3/archives

# Configure Apache
RUN a2enmod perl rewrite headers ssl expires && \
    a2dissite 000-default

# Copy custom entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

# Expose HTTP port
EXPOSE 80

# Set entrypoint
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
CMD ["apache2ctl", "-D", "FOREGROUND"]

Step 3: Create the Entrypoint Script

Create a docker-entrypoint.sh script that initializes EPrints and configures the database connection:

#!/bin/bash
set -e

# Environment variables with defaults
DB_HOST=${DB_HOST:-mysql}
DB_PORT=${DB_PORT:-3306}
DB_NAME=${DB_NAME:-eprints}
DB_USER=${DB_USER:-eprints}
DB_PASS=${DB_PASS:-changeme}
REPO_ID=${REPO_ID:-repository}
REPO_NAME=${REPO_NAME:-"My Repository"}
ADMIN_EMAIL=${ADMIN_EMAIL:-admin@example.org}
REPO_HOST=${REPO_HOST:-example-app.klutch.sh}

echo "Starting EPrints initialization..."

# Wait for database to be ready
echo "Waiting for database at ${DB_HOST}:${DB_PORT}..."
until mysql -h ${DB_HOST} -P ${DB_PORT} -u ${DB_USER} -p${DB_PASS} -e "SELECT 1" &>/dev/null; do
    echo "Database not ready, waiting..."
    sleep 3
done
echo "Database is ready!"

# Check if repository already exists
if [ ! -d "/opt/eprints3/archives/${REPO_ID}" ]; then
    echo "Creating new repository: ${REPO_ID}"

    # Switch to eprints user for repository creation
    su - eprints -c "cd /opt/eprints3 && cat > /tmp/eprints_answers.txt << EOF
${REPO_ID}
${REPO_HOST}
80
${ADMIN_EMAIL}
${REPO_NAME}
${DB_HOST}
${DB_NAME}
${DB_USER}
${DB_PASS}
${DB_PORT}
UTF-8
en
/opt/eprints3/archives/${REPO_ID}/documents
EOF
    /opt/eprints3/bin/epadmin create < /tmp/eprints_answers.txt"

    echo "Repository created successfully"

    # Create initial admin user
    su - eprints -c "/opt/eprints3/bin/epadmin create_user ${REPO_ID} << EOF
admin
admin@example.org
changeme
admin
EOF"

    echo "Admin user created (username: admin, password: changeme)"
    echo "IMPORTANT: Change the admin password after first login!"
else
    echo "Repository already exists at /opt/eprints3/archives/${REPO_ID}"
fi

# Generate Apache configuration
echo "Generating Apache configuration..."
su - eprints -c "/opt/eprints3/bin/epadmin generate_apacheconf --system"
cp /opt/eprints3/cfg/apache.conf /etc/apache2/sites-available/eprints.conf
a2ensite eprints

# Update repository configuration if environment variables changed
echo "Updating repository configuration..."
perl -pi -e "s/^\\\$c->{host}\s*=.*/\\\$c->{host} = '${REPO_HOST}';/" /opt/eprints3/archives/${REPO_ID}/cfg/cfg.d/00_core.pl
perl -pi -e "s/^\\\$c->{port}\s*=.*/\\\$c->{port} = 80;/" /opt/eprints3/archives/${REPO_ID}/cfg/cfg.d/00_core.pl

# Reload configuration
echo "Reloading EPrints configuration..."
su - eprints -c "/opt/eprints3/bin/epadmin reload ${REPO_ID}"

# Start indexer in background
echo "Starting indexer..."
su - eprints -c "/opt/eprints3/bin/indexer ${REPO_ID} start" || true

echo "EPrints initialization complete!"
echo "Repository URL: http://${REPO_HOST}"
echo "Admin interface: http://${REPO_HOST}/cgi/users/home"

# Execute the main command
exec "$@"

Step 4: Create a README

Create a README.md file documenting your EPrints setup:

# EPrints Institutional Repository

This repository contains the Docker configuration for deploying EPrints on Klutch.sh.

## Quick Start

1. Set up a MySQL database on Klutch.sh
2. Push this repository to GitHub
3. Deploy on Klutch.sh with environment variables configured
4. Access your repository at your Klutch.sh URL

## Default Credentials

- Username: `admin`
- Password: `changeme` (change immediately after first login)

## Environment Variables

Required:
- `DB_HOST`: MySQL host (from Klutch.sh MySQL app)
- `DB_NAME`: Database name (default: eprints)
- `DB_USER`: Database user (default: eprints)
- `DB_PASS`: Database password
- `REPO_HOST`: Your Klutch.sh app URL

Optional:
- `REPO_ID`: Repository identifier (default: repository)
- `REPO_NAME`: Display name for repository
- `ADMIN_EMAIL`: Administrator email address

## Persistent Storage

Mount volumes to:
- `/opt/eprints3/archives` - Repository archives and documents

## Support

For EPrints documentation, visit https://wiki.eprints.org

Step 5: Test Locally (Optional)

Create a docker-compose.yml for local testing:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: eprints
      MYSQL_USER: eprints
      MYSQL_PASSWORD: eprintspass
    volumes:
      - mysql_data:/var/lib/mysql
    ports:
      - "3306:3306"

  eprints:
    build: .
    ports:
      - "8080:80"
    environment:
      DB_HOST: mysql
      DB_NAME: eprints
      DB_USER: eprints
      DB_PASS: eprintspass
      REPO_HOST: localhost:8080
      REPO_ID: myrepo
      REPO_NAME: "My Institutional Repository"
      ADMIN_EMAIL: admin@institution.edu
    volumes:
      - eprints_archives:/opt/eprints3/archives
    depends_on:
      - mysql

volumes:
  mysql_data:
  eprints_archives:

Test locally:

# Build and start services
docker-compose up -d

# Wait for initialization (check logs)
docker-compose logs -f eprints

# Access EPrints at http://localhost:8080
# Admin login at http://localhost:8080/cgi/users/home
# Username: admin, Password: changeme

# Stop services when done testing
docker-compose down

Step 6: Push to GitHub

Commit your files and push to GitHub:

git add Dockerfile docker-entrypoint.sh README.md .gitignore
git commit -m "Initial EPrints Docker setup"
git remote add origin https://github.com/yourusername/eprints-klutch.git
git push -u origin main

Create a .gitignore file:

# Docker
docker-compose.yml
.env

# EPrints
archives/*
!archives/.gitkeep

# OS
.DS_Store
Thumbs.db

Deploying to Klutch.sh

Now that your EPrints repository is ready, follow these steps to deploy it on Klutch.sh.

Prerequisites: Deploy MySQL Database

Before deploying EPrints, set up a MySQL database:

Deploy MySQL on Klutch.sh

Follow the MySQL deployment guide to create a database instance. Note the connection details provided after deployment.

Create EPrints Database

Connect to your MySQL instance and create a database for EPrints:

CREATE DATABASE eprints CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'eprints'@'%' IDENTIFIED BY 'secure_password_here';
GRANT ALL PRIVILEGES ON eprints.* TO 'eprints'@'%';
FLUSH PRIVILEGES;

Note Connection Details

Save these for use in EPrints deployment:
- Database host: your-mysql-app.klutch.sh:8000
- Database name: eprints
- Database user: eprints
- Database password: (your secure password)

Deployment Steps

Log in to Klutch.sh

Navigate to klutch.sh/app and sign in to your account.
Create a New Project

Click “Create Project” and give it a descriptive name like “Institutional Repository” or “Research Archive”.
Create a New App

Navigate to “Create App” within your project:
- App Name: Give it a clear name like “EPrints Repository”
- Git Source: Select GitHub
- Repository: Choose your EPrints repository
- Branch: Select main or your deployment branch
Configure Traffic Type
- Traffic Type: Select HTTP (EPrints serves web pages)
- Internal Port: Set to 80 (EPrints’ Apache server default port)
Set Environment Variables

Add the following environment variables with your MySQL connection details:

Required Variables:
```
DB_HOST=your-mysql-app.klutch.sh
DB_PORT=8000
DB_NAME=eprints
DB_USER=eprints
DB_PASS=your_secure_password
REPO_HOST=your-eprints-app.klutch.sh
```
Optional Variables:
```
REPO_ID=repository
REPO_NAME=My Institutional Repository
ADMIN_EMAIL=admin@institution.edu
```
Important: The REPO_HOST should match your Klutch.sh app URL (which you’ll receive after deployment).
Attach Persistent Volume

EPrints stores research documents and archives in the file system, so persistent storage is essential:
- Click “Add Volume” in the Volumes section
- Mount Path: /opt/eprints3/archives
- Size: Start with at least 20GB, scale based on your expected collection size
  - Small repository (<10,000 items): 20-50GB
  - Medium repository (10,000-100,000 items): 100-500GB
  - Large repository (>100,000 items): 1TB+
Note: All research documents, PDFs, images, and data files will be stored here. Ensure adequate space for growth.
Configure Resources

Select appropriate compute resources:
- CPU: 2+ cores recommended (Perl benefits from multiple cores for indexing)
- Memory: Minimum 2GB, 4GB+ recommended for production
- Region: Choose the region closest to your primary users
Deploy Your Repository

Click “Create” to start the deployment. Klutch.sh will:
- Detect your Dockerfile automatically
- Build the EPrints container with all dependencies
- Connect to your MySQL database
- Initialize the repository with your configuration
- Attach the persistent volume for archives
- Assign a URL for accessing your repository
Monitor Deployment

Watch the build logs for any errors. Initial setup takes 5-10 minutes as EPrints:
- Creates database tables
- Generates configuration files
- Sets up the Apache virtual host
- Creates the initial admin user
- Starts the indexer service
Access Your Repository

Once deployment completes, you’ll receive a URL like your-eprints-app.klutch.sh.
- Public Interface: https://your-eprints-app.klutch.sh
- Admin Login: https://your-eprints-app.klutch.sh/cgi/users/home
- Default Credentials: Username admin, Password changeme
IMPORTANT: Change the admin password immediately after first login!

Post-Deployment Configuration

After successful deployment, configure EPrints for your institutional needs.

Change Admin Password

Log in as Admin

Navigate to https://your-eprints-app.klutch.sh/cgi/users/home and log in with default credentials (username: admin, password: changeme).
Navigate to User Settings

Click on your username in the top right, then “Edit Details”.
Update Password

Under the “Security” section, change your password to a strong, unique password. Save changes.
Update Email Address

Change the default email address to your institutional email for notifications.

Configure Repository Settings

Edit key configuration files through the admin interface or by updating environment variables:

Basic Settings (Admin → System Settings):

Repository name and description
Contact email addresses
Institution name and logo
Default language and timezone

Metadata Fields (Admin → Config Tools → Metadata Fields):

Customize fields for your research outputs
Add custom fields for grants, projects, or institutional units
Configure controlled vocabularies for subjects and keywords

Submission Workflow (Admin → Config Tools → Workflows):

Define review stages (direct deposit, mediation, peer review)
Set up approval chains for different content types
Configure email notifications for workflow events

User Roles (Admin → Config Tools → User Roles):

Create roles for depositors, editors, and administrators
Assign permissions for viewing, editing, and managing content
Set up deposit privileges by department or user type

Set Up Depositor Accounts

Create accounts for researchers who will deposit work:

Navigate to User Management

Go to Admin → Manage Users → Create User.
Enter User Details
- Username (typically institutional ID)
- Email address
- Full name
- User type (select “User” for depositors)
Assign Privileges

Grant “Deposit” privilege for the repository. Optionally assign “Editor” role for users who will review submissions.
Send Welcome Email

EPrints can automatically email login credentials. Alternatively, manually share credentials securely.

Configure OAI-PMH Harvesting

Enable metadata harvesting for aggregators like OpenDOAR and BASE:

# In /opt/eprints3/archives/repository/cfg/cfg.d/oai.pl
$c->{oai}->{v2}->{archive_id} = "oai:your-institution.edu:repository";
$c->{oai}->{v2}->{repository_name} = "My Institutional Repository";
$c->{oai}->{v2}->{admin_email} = "admin@institution.edu";
$c->{oai}->{v2}->{metadata_formats} = {
    oai_dc => {
        namespace => "http://www.openarchives.org/OAI/2.0/oai_dc/",
        schema => "http://www.openarchives.org/OAI/2.0/oai_dc.xsd",
    },
};

Test your OAI-PMH endpoint: https://your-eprints-app.klutch.sh/cgi/oai2

Using EPrints

Depositing Research Outputs

Researchers can deposit work through the web interface:

Log In

Navigate to https://your-eprints-app.klutch.sh/cgi/users/home and log in with institutional credentials.
Start New Deposit

Click “Manage Deposits” → “New Item”.
Select Item Type

Choose the appropriate type:
- Journal Article
- Conference Paper
- Book Chapter
- Thesis
- Dataset
- Technical Report
Enter Metadata

Fill in required fields:
- Title
- Authors (with ORCID IDs if available)
- Abstract
- Publication date
- Publisher/venue
- Keywords and subjects
- DOI (if available)
Upload Files
- Click “Upload” to add PDF, Word documents, or data files
- Multiple files can be attached to a single item
- Specify file format and access rights for each file
Set Access Rights

Choose visibility:
- Open Access: Publicly accessible immediately
- Embargoed: Accessible after a specified date
- Restricted: Accessible only to authenticated users
- Metadata Only: Only bibliographic information visible
Submit for Review

Click “Deposit Item” to submit. Depending on workflow configuration, items may require editorial review before publication.

Managing the Repository

Reviewing Submissions (Admin → Review):

View pending deposits awaiting approval
Edit metadata for quality control
Accept or request changes
Bulk operations for batch processing

Search and Browse (Public Interface):

Full-text search across metadata and document content
Browse by author, subject, date, or department
RSS feeds for new additions
Export citations in BibTeX, RIS, EndNote formats

Statistics and Reports (Admin → Statistics):

Download counts by item, author, or department
Monthly and annual reports
Top accessed items
Geographic distribution of users

Batch Operations (Admin → Batch Import):

Import from RIS, BibTeX, or CSV files
Bulk upload from reference managers like Zotero or Mendeley
Automated harvesting from publisher APIs

Production Best Practices

Security Recommendations

User Authentication:

Integrate with institutional LDAP or Shibboleth for single sign-on
Enforce strong password policies
Enable two-factor authentication if your institution requires it
Regularly audit user accounts and remove inactive users

Access Control:

Restrict admin interface to institutional IP ranges if possible
Use granular permissions—not all users need deposit privileges
Review and approve metadata changes by non-admin users
Log all administrative actions for audit trails

Data Protection:

Enable HTTPS for all repository access (handled automatically by Klutch.sh)
Encrypt database credentials using environment variables
Regularly backup the MySQL database and file archives
Test restoration procedures periodically

API Security:

Restrict SWORD API access with authentication tokens
Rate-limit OAI-PMH harvesting to prevent abuse
Monitor for suspicious activity in access logs

Performance Optimization

Database Tuning:

Add indexes on frequently queried metadata fields
Use MySQL query cache for repeated searches
Consider read replicas for high-traffic repositories
Optimize full-text search with dedicated Xapian service

Caching:

Enable Apache’s mod_cache for static content
Configure EPrints’ view cache for browse pages
Use CDN for document downloads in high-traffic scenarios
Cache OAI-PMH responses to reduce database load

Indexing:

Schedule indexer to run during off-peak hours
Increase indexer frequency during heavy deposit periods
Monitor indexer logs for errors or delays
Consider separate indexing server for very large repositories (>100,000 items)

File Storage:

Use fast SSD storage for archives directory
Implement automatic thumbnail generation for images and PDFs
Compress older documents that are rarely accessed
Archive superseded versions to secondary storage

Backup and Recovery

Database Backups:

# Daily backup script (run as cron job)
mysqldump -h your-mysql-app.klutch.sh -P 8000 \
  -u eprints -p eprints > eprints_backup_$(date +%Y%m%d).sql

# Restore from backup
mysql -h your-mysql-app.klutch.sh -P 8000 \
  -u eprints -p eprints < eprints_backup_20250101.sql

Archive Backups:

Backup the /opt/eprints3/archives volume regularly
Use incremental backups for large collections
Store backups in geographically separate locations
Verify backup integrity monthly

Disaster Recovery Plan:

Document all environment variables and configuration
Keep copies of custom Perl code and templates
Maintain a staging environment for testing updates
Practice full restoration at least annually

Compliance and Standards

Open Access Mandates:

Configure embargo periods to comply with publisher policies
Set up automatic email reminders for embargo expiration
Track compliance with funder open access requirements
Generate reports for institutional assessment

Metadata Quality:

Enforce required fields in deposit forms
Use controlled vocabularies for consistency
Validate DOIs and ISBNs automatically
Implement peer review for metadata accuracy

Preservation:

Generate checksums for all uploaded files
Monitor for file corruption and bit rot
Plan for format migration as standards evolve
Document preservation policies in repository guidelines

Accessibility:

Ensure web interface meets WCAG 2.1 AA standards
Provide alt text for images and figures
Support screen readers and keyboard navigation
Offer multiple download formats for broader accessibility

Troubleshooting

Repository Not Loading

Symptom: EPrints shows a blank page or Apache error.

Solutions:

Check that the database connection is working: mysql -h DB_HOST -P 8000 -u DB_USER -p
Verify environment variables are set correctly in Klutch.sh dashboard
Review Apache error logs: docker logs <container-id>
Ensure the REPO_HOST matches your actual Klutch.sh app URL
Restart the indexer: /opt/eprints3/bin/indexer repository restart

Database Connection Errors

Symptom: “Can’t connect to MySQL server” errors in logs.

Solutions:

Verify MySQL app is running on Klutch.sh
Check database credentials in environment variables
Ensure database user has correct permissions
Test connection from EPrints container: mysql -h $DB_HOST -P $DB_PORT -u $DB_USER -p
Verify firewall rules allow connections on port 8000

Uploads Failing

Symptom: File uploads fail or return “Permission Denied” errors.

Solutions:

Verify persistent volume is correctly mounted at /opt/eprints3/archives
Check volume has sufficient space available
Ensure eprints user has write permissions to archive directory
Increase max upload size in Apache configuration if needed
Check PHP post_max_size and upload_max_filesize limits

Search Not Working

Symptom: Search returns no results or outdated results.

Solutions:

Manually trigger reindexing: /opt/eprints3/bin/indexer repository start
Check indexer is running: ps aux | grep indexer
Verify database tables are not corrupted: mysqlcheck eprints
Rebuild search indexes: /opt/eprints3/bin/epadmin reindex repository
Check for errors in indexer logs

Slow Performance

Symptom: Pages load slowly or time out.

Solutions:

Increase memory allocation in Klutch.sh dashboard (min 4GB recommended)
Add database indexes on frequently queried fields
Enable EPrints view caching
Reduce indexer frequency if it’s consuming too many resources
Consider upgrading to larger compute resources
Profile slow queries with MySQL slow query log

Metadata Not Displaying

Symptom: Deposited items missing metadata fields.

Solutions:

Check metadata field configuration in Admin → Config Tools
Verify custom fields are properly defined in dataset XML
Reload repository configuration: /opt/eprints3/bin/epadmin reload repository
Clear view cache: /opt/eprints3/bin/epadmin refresh_views repository
Review field permissions and visibility settings

Advanced Configuration

Custom Themes

Create a custom theme for your institution:

Create Theme Directory

mkdir -p /opt/eprints3/archives/repository/cfg/static
mkdir -p /opt/eprints3/archives/repository/cfg/lang/en/templates

Add Custom CSS

Create /opt/eprints3/archives/repository/cfg/static/style/custom.css:

/* Institutional branding */
#header {
    background: #003366;
    color: white;
}

.ep_tm_menu a {
    color: white;
}

h1, h2, h3 {
    color: #003366;
}

Add Institutional Logo

Copy your logo to /opt/eprints3/archives/repository/cfg/static/images/logo.png.
Update Template

Edit /opt/eprints3/archives/repository/cfg/lang/en/templates/default.xml to include custom CSS and logo.

Enable ORCID Integration

Connect researcher profiles with ORCID identifiers:

# In /opt/eprints3/archives/repository/cfg/cfg.d/orcid.pl
$c->{orcid}->{api_url} = "https://pub.orcid.org/v2.0";
$c->{orcid}->{client_id} = "APP-XXXXXXXXX";
$c->{orcid}->{client_secret} = "your-client-secret";
$c->{orcid}->{enable_import} = 1;

Configure DOI Minting

Set up automatic DOI assignment with DataCite:

# In /opt/eprints3/archives/repository/cfg/cfg.d/datacite.pl
$c->{datacite}->{username} = "your-datacite-username";
$c->{datacite}->{password} = "your-datacite-password";
$c->{datacite}->{prefix} = "10.5555";
$c->{datacite}->{shoulder} = "EPR";
$c->{datacite}->{mint_on_publish} = 1;

Set Up Email Notifications

Configure SMTP for workflow notifications:

# In /opt/eprints3/archives/repository/cfg/cfg.d/email.pl
$c->{smtp_server} = "smtp.institution.edu";
$c->{smtp_port} = 587;
$c->{smtp_username} = "noreply@institution.edu";
$c->{smtp_password} = "email-password";
$c->{smtp_use_tls} = 1;

Additional Resources

Conclusion

Deploying EPrints on Klutch.sh provides a powerful, scalable institutional repository solution that meets the needs of modern research institutions. With automated Docker deployment, persistent storage for research archives, integrated MySQL database support, and comprehensive metadata management, your repository is ready to support open access mandates, research visibility, and long-term digital preservation. Whether you’re managing thousands of journal articles, hosting research datasets, or archiving institutional theses, EPrints on Klutch.sh delivers the reliability and features needed for world-class digital repositories.