Deploying I, Librarian

Introduction

I, Librarian is an open-source reference management application designed for researchers, academics, and anyone who needs to organize large collections of PDFs and academic papers. Built with PHP and SQLite, it provides a web-based interface for managing your research library with powerful PDF annotation, full-text search, and citation management capabilities.

Unlike cloud-based reference managers, I, Librarian gives you complete control over your research data. Your PDFs and metadata stay on your own infrastructure, ensuring privacy and eliminating concerns about subscription costs or service discontinuation.

Key highlights of I, Librarian:

PDF Management: Upload, organize, and annotate PDF documents with a built-in viewer
Full-Text Search: Search across all your documents’ content, not just metadata
Citation Management: Generate citations in various formats (BibTeX, RIS, EndNote)
Metadata Import: Fetch metadata from PubMed, CrossRef, NASA ADS, and other sources
Projects: Organize documents into projects for different research topics
Notes and Highlights: Annotate PDFs with notes, highlights, and bookmarks
Supplements: Attach supplementary files to your references
Multi-User Support: Share your library with collaborators
Office Integration: Export citations directly to word processors
API Access: Programmatic access for integration with other tools

This guide walks through deploying I, Librarian on Klutch.sh using Docker, setting up persistent storage for your research library.

Why Deploy I, Librarian on Klutch.sh

Deploying I, Librarian on Klutch.sh provides several advantages for managing your research library:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds I, Librarian without complex server configuration. Push to GitHub, and your reference manager deploys automatically.

Persistent Storage: Attach persistent volumes for your PDF library and database. Your documents and annotations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your research materials from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Accessible Anywhere: Access your research library from any device with a web browser, whether at home, office, or traveling.

Scalable Storage: Allocate storage based on your library size. Start small and expand as your collection grows.

Custom Domains: Assign a custom domain for a professional research portal experience.

Prerequisites

Before deploying I, Librarian on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your I, Librarian configuration
Basic familiarity with Docker and containerization concepts
Your existing PDF library ready to upload (optional)

Understanding I, Librarian Architecture

I, Librarian is built with simplicity in mind:

PHP Application: The web interface and backend are built with PHP, running on Apache or Nginx.

SQLite Database: Metadata and user information are stored in SQLite, eliminating the need for a separate database server.

File-Based Storage: PDFs and attachments are stored directly on the filesystem, making backup and migration straightforward.

Full-Text Index: A search index enables fast full-text search across all documents.

Preparing Your Repository

To deploy I, Librarian on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

i-librarian-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM cgrima/i-librarian:latest

# Set environment variables
ENV TZ=${TZ:-UTC}
ENV PHP_MEMORY_LIMIT=${PHP_MEMORY_LIMIT:-256M}
ENV PHP_UPLOAD_MAX_FILESIZE=${PHP_UPLOAD_MAX_FILESIZE:-100M}
ENV PHP_POST_MAX_SIZE=${PHP_POST_MAX_SIZE:-100M}

# Create data directories
RUN mkdir -p /app/data/library /app/data/database

# Set permissions
RUN chown -R www-data:www-data /app/data

# Expose the web interface port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

# Volume for persistent data
VOLUME ["/app/data"]

Alternative Custom Build

If you need more customization:

FROM php:8.1-apache

# Install required extensions and dependencies
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    poppler-utils \
    tesseract-ocr \
    ghostscript \
    wget \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# Configure PHP extensions
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd pdo pdo_sqlite zip

# Configure PHP settings
RUN echo "memory_limit=256M" >> /usr/local/etc/php/conf.d/custom.ini \
    && echo "upload_max_filesize=100M" >> /usr/local/etc/php/conf.d/custom.ini \
    && echo "post_max_size=100M" >> /usr/local/etc/php/conf.d/custom.ini

# Download and install I, Librarian
WORKDIR /var/www/html
RUN wget -O ilibrarian.zip https://github.com/mkuber/i-librarian-free/releases/latest/download/i-librarian.zip \
    && unzip ilibrarian.zip \
    && rm ilibrarian.zip

# Set permissions
RUN chown -R www-data:www-data /var/www/html

# Enable Apache rewrite module
RUN a2enmod rewrite

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`TZ`	No	UTC	Server timezone
`PHP_MEMORY_LIMIT`	No	256M	PHP memory limit
`PHP_UPLOAD_MAX_FILESIZE`	No	100M	Maximum upload file size
`PHP_POST_MAX_SIZE`	No	100M	Maximum POST request size

Deploying I, Librarian on Klutch.sh

Once your repository is prepared, follow these steps to deploy I, Librarian:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial I, Librarian deployment configuration"
git remote add origin https://github.com/yourusername/i-librarian-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “research-library” or “i-librarian”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your I, Librarian Dockerfile.

Configure HTTP Traffic

I, Librarian serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

In the environment variables section, configure your instance:

Variable	Value
`TZ`	Your timezone (e.g., `America/New_York`)
`PHP_UPLOAD_MAX_FILESIZE`	`100M` (adjust for large PDFs)
`PHP_POST_MAX_SIZE`	`100M`

Attach Persistent Volumes

Persistent storage is essential for your research library. Add the following volume:

Mount Path	Recommended Size	Purpose
`/app/data`	50+ GB	PDFs, database, and application data

Size your volume based on your expected library size. Academic PDFs typically range from 1-50 MB each.

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the I, Librarian container
Provision an HTTPS certificate

Access I, Librarian

Once deployment completes, access your I, Librarian instance at https://your-app-name.klutch.sh. Complete the initial setup wizard to configure your library.

Initial Configuration

First-Time Setup

When you first access I, Librarian, complete the setup wizard:

Database Setup: The application will initialize the SQLite database
Admin Account: Create your administrator account
Library Settings: Configure your library name and preferences

Importing References

I, Librarian supports multiple import methods:

Manual Upload: Upload PDFs directly through the web interface
DOI Import: Enter a DOI to automatically fetch metadata
PubMed Import: Search and import from PubMed
BibTeX Import: Import existing BibTeX libraries
File Import: Batch import from a folder of PDFs

Using the PDF Viewer

I, Librarian includes a powerful PDF viewer:

Open any document in your library
Use the annotation toolbar to add highlights and notes
Create bookmarks for important sections
Export annotated PDFs

Citation Management

Generate citations for your documents:

Select documents from your library
Choose export format (BibTeX, RIS, EndNote, etc.)
Copy formatted citations for your papers

Multi-User Setup

Adding Users

To share your library with collaborators:

Go to Administration in the settings
Create new user accounts
Assign appropriate permissions

Permission Levels

Level	Capabilities
Admin	Full access including user management
User	Can add, edit, and annotate documents
Guest	Read-only access to the library

Troubleshooting Common Issues

Cannot Upload Large PDFs

Symptoms: Upload fails for large files.

Solutions:

Increase PHP_UPLOAD_MAX_FILESIZE and PHP_POST_MAX_SIZE
Check that the volume has sufficient space
Verify PHP memory limit is adequate

Search Not Finding Content

Symptoms: Full-text search returns no results.

Solutions:

Ensure the search index has been built
Verify PDFs contain searchable text (not just images)
Run OCR on scanned documents

Slow Performance

Symptoms: Application responds slowly.

Solutions:

Increase PHP memory limit
Allocate more CPU resources in Klutch.sh
Optimize your library structure with projects

Backup and Migration

Backing Up Your Library

Your entire library is stored in the /app/data volume:

SQLite database with all metadata
PDF files and attachments
User settings and annotations

Migrating from Another System

To migrate from desktop reference managers:

Export your library to BibTeX format
Import the BibTeX file to I, Librarian
Upload associated PDF files
Link PDFs to imported references

Additional Resources

Conclusion

Deploying I, Librarian on Klutch.sh gives you a powerful, self-hosted reference management system with automatic builds, persistent storage, and secure HTTPS access. You maintain full control over your research data while enjoying the convenience of web-based access from anywhere.

Whether you’re managing a personal research library or setting up a shared resource for your research group, I, Librarian on Klutch.sh provides the foundation for organized, searchable, and properly cited academic work.