SecureAnyCloud
Deployment guide

I Librarian

Overview

This guide covers the deployment and configuration of I, Librarian on Ubuntu 24.04 on Azure, using SecureAnyCloud Azure Marketplace images. I, Librarian is a self-hosted reference and PDF management system for research groups, laboratories and libraries. Martin Kucej develops it, and it is published at github.com/mkucej/i-librarian-free.

You upload PDFs, and I, Librarian extracts and indexes their full text and fetches bibliographic metadata. You read and annotate papers in the browser, and you organize everything with tags, categories and shared projects.

The image installs I, Librarian 5.11.3, served by nginx and PHP 8.3 FPM and backed by an on-box SQLite database. There is no external database server to run or secure. poppler provides full-text PDF indexing and the built-in PDF viewer, ghostscript backs the viewer, and Tesseract provides optional OCR of scanned documents. Unattended security upgrades keep the server patched on your running VM.

One appliance, one web application. I, Librarian is a front-controller application. nginx and php8.3-fpm serve the whole site on port 80 and route every request through the application's public/index.php. The SQLite database, your uploaded PDFs, the configuration and the application source all live outside the web root. Only the web interface is reachable, and your library data is never served as source.

Security by design: there is no administrator account in the image. I, Librarian grants administrator rights to the first account created on a fresh library, and it auto-creates its database on the first web request. That would let an unauthenticated visitor register as the first administrator. This image closes that hole completely. It ships no account and no database at all.

On the very first boot of every VM, a one-shot service generates a unique administrator password. It creates the SQLite database and the single administrator account, disables public self-registration and sets new-account permissions to regular user. The service then proves that the new password signs in through the real sign-in form and that admin, a blank password and other common guesses do not. Only then does it write /root/i-librarian-credentials.txt (mode 0600, root only).

The site cannot serve an unprovisioned instance. nginx and php8.3-fpm are each gated on a bootstrap marker that first boot writes only after the database and administrator account are in place. Until that marker exists, systemd skips those units entirely. No half-provisioned site, and no empty library where the first visitor becomes administrator, is ever reachable. The units are still enabled, so the appliance comes straight back after a reboot.

What you get:

  • I, Librarian 5.11.3 served by nginx and PHP 8.3 FPM, routing every request through the application front controller
  • An on-box SQLite database holding your library, with no external database server to manage
  • The poppler, ghostscript and tesseract-ocr toolchain for full-text PDF indexing, the built-in PDF viewer and optional OCR of scanned documents
  • A first-boot service that mints a per-instance administrator password, seeds the administrator, disables self-signup, and proves the credentials before the site is reachable
  • The bootstrap gate that stops nginx and php-fpm from serving until provisioning is complete

Prerequisites

  • An Azure subscription and either the Azure Portal or the Azure CLI (az) signed in
  • An SSH key pair, so you can read the generated credentials file
  • Inbound TCP port 80 open to the browsers that will reach the library, and port 22 open for administration
1

Deploy from the Azure Portal

  • Open the SecureAnyCloud I, Librarian Reference Manager on Ubuntu 24.04 LTS offer in the Azure Marketplace and choose Create.
  • Pick a resource group and region. Keep the recommended Standard_B2s size (2 vCPU / 4 GB is comfortable for a lab library), and provide your SSH public key for the azureuser account.
  • On the Networking step, allow inbound 80 (the web application) and 22 (SSH). I, Librarian serves everything over port 80. If you want TLS, put it behind an Azure Application Gateway or a reverse proxy.
  • Create the VM and note its public IP address.
2

Deploy from the Azure CLI

RG="i-librarian-prod"; LOCATION="eastus"; VM_NAME="i-librarian" IMAGE_URN="sac1647283583153:i-librarian-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:i-librarian-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 80 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002
3

First boot and your credentials

On first boot, the image mints the per-instance administrator password, creates the SQLite database and seeds the single administrator account. It disables self-registration, opens the bootstrap gate and starts nginx and php-fpm. It then verifies that the new credentials work and that the common defaults are rejected, and writes /root/i-librarian-credentials.txt. This completes within a minute or two.

SSH in as azureuser and read the details:

sudo cat /root/i-librarian-credentials.txt

The file gives you the library URL, the administrator username (admin) and the per-instance administrator password. Keep the file safe. Only root can read it.

4

Confirm the appliance is running

Both services should report active. The ss command confirms that the web application is on port 80. The SQLite databases sit on the local disk, so there is no network database to expose.

systemctl is-active php8.3-fpm.service nginx.service sed -n "s/.*IL_VERSION = '\([^']*\)'.*/I, Librarian \1/p" /var/www/i-librarian/public/index.php | head -1 php -r 'echo "PHP ".PHP_VERSION."\n";' ss -tulnp | grep ':80 ' | sed 's/users:.*//' ls -la /var/www/i-librarian/data/database/ | grep '\.db$'
5

Sign in to I, Librarian

Browse to http://<your-vm-ip>/. The I, Librarian sign-in page appears. Sign in with the administrator username admin and the password from the credentials file.

Once you are signed in, you land on the dashboard. The library, import tools, projects, catalog and administrator panel are all one click away.

6

Change the administrator password

Open the account menu (top right), choose your profile, and set a new password. From then on, use your own password. The generated password in the credentials file only gets you in the first time.

7

Add your first reference

From Import, you can add references by identifier (DOI, PubMed ID, arXiv, Crossref and more) or upload published PDFs. You can also enter a reference by hand with Manual import and attach the PDF as you go.

I, Librarian extracts the full text of every PDF with pdftotext, so the paper becomes searchable the moment you import it. Imported references appear in your Library.

8

Read, search and organize

Opening a reference shows its summary page. The page holds the metadata, the abstract, the notes and discussion, the tags, and the attached PDF. You can read the PDF in the built-in viewer, download it, or manage it.

Use Search and Filter for full-text and fielded search across the whole library. Group papers into shared Projects, and label them with Tags and Categories.

The whole library lives in the on-box SQLite database and the PDF store, served on port 80. That includes references, uploaded PDFs, tags, projects and settings.

9

Prove the per-VM administrator works and defaults are rejected

The image ships no shared credential. The credentials file is root-only. The real sign-in form accepts only the per-VM administrator password, and the configuration and the database are never web-served:

ls -l /root/i-librarian-credentials.txt stat -c 'credentials mode %a owner %U:%G' /root/i-librarian-credentials.txt
# the per-VM administrator password signs in through the real form:
sudo /usr/local/sbin/i-librarian-login-check.sh admin '<ILIBRARIAN_ADMIN_PASSWORD>' \
  && echo "per-VM administrator: SIGNED IN" \
  || echo "per-VM administrator: run this on your VM (the password is substituted from the credentials file)"
# every guessable default is rejected: for p in admin password librarian ilibrarian 123456 ""; do if
sudo /usr/local/sbin/i-librarian-login-check.sh admin "$p"; then echo " '$p' ACCEPTED (unexpected)" else echo " '$p' rejected (correct)" fi done
# the config and the database are never web-served:
curl -s -o /dev/null -w ' GET /config/ilibrarian.ini -> HTTP %{http_code} (404 = not served)\n' http://127.0.0.1/config/ilibrarian.ini
curl -s -o /dev/null -w ' GET /data/database/main.db -> HTTP %{http_code} (404 = not served)\n' http://127.0.0.1/data/database/main.db
10

OCR and metadata lookup

I, Librarian ships with Tesseract for OCR of scanned PDFs. The OCR path is preconfigured to /usr/bin/tesseract. I, Librarian can also fetch bibliographic metadata for a reference from Crossref, PubMed, arXiv, NASA ADS and other sources.

Both features are available from the Administrator > Global settings page and from a reference's own tools. You need no extra configuration to get started.

11

How the first-boot gate protects an unprovisioned instance

The distinguishing security property of this image is that the web tier cannot serve until provisioning is complete. Each web unit carries a ConditionPathExists drop-in on the bootstrap-ready marker.

First boot writes that marker only after the administrator has been seeded. There is therefore never a moment when an empty library is reachable and the first visitor could become administrator.

grep -H ConditionPathExists /etc/systemd/system/nginx.service.d/sac-bootstrap-gate.conf for u in php8.3-fpm nginx; do printf '%-12s %s\n' "$u" "$(grep -h ConditionPathExists /etc/systemd/system/$u.service.d/sac-bootstrap-gate.conf)" done ls -l /var/lib/sac/data/ systemctl is-enabled php8.3-fpm.service nginx.service
12

Add more users

Self-registration is disabled by default, so only an administrator can create new accounts. From Administrator > Users, you can add colleagues, set their permissions (administrator, regular user or guest), and manage their access.

New accounts default to regular user, so only accounts that you explicitly promote get administrator rights.

13

Back up and restore

The whole library lives under /var/www/i-librarian/data. That includes references, tags, projects, settings and the uploaded PDFs. The SQLite databases are in data/database, and the documents are in data/pdfs and data/supplements. Back up the library with a routine archive:

sudo tar czf "i-librarian-$(date +%F).tar.gz" -C /var/www/i-librarian data

To restore into a fresh instance, extract the archive back over /var/www/i-librarian/data. Stop the web units first, then run sudo chown -R www-data:www-data /var/www/i-librarian/data.

14

Security recommendations

  • Put I, Librarian behind TLS. The image serves plain HTTP on port 80. Terminate HTTPS at an Azure Application Gateway, a load balancer, or a reverse proxy in front of the VM, and restrict port 80 to that front end.
  • Restrict SSH to your administration network with an NSG rule.
  • Rotate the administrator password (Step 6), and keep the credentials file (/root/i-librarian-credentials.txt) readable only by root.
  • Keep self-registration disabled unless you deliberately want open sign-up. New accounts default to regular user.
  • Keep the OS patched. Unattended security upgrades are enabled. Reboot periodically to pick up new kernels.
  • Back up regularly (Step 13), especially before a large import.
15

Support and licensing

I, Librarian is distributed under the GNU General Public License v3.0. The license text ships at /var/www/i-librarian/LICENSE. This SecureAnyCloud image bundles I, Librarian 5.11.3 with nginx, PHP, SQLite and the poppler/ghostscript/Tesseract toolchain from Ubuntu 24.04, configured and hardened as described above.

SecureAnyCloud provides 24/7 support for this image by email at sales@secureanycloud.com. We help with library setup, PDF import and full-text indexing, OCR configuration, metadata lookup, user and project management, citation export, backup and restore, performance tuning and I, Librarian version upgrades.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on Azure

Launch I, Librarian 5.11.3 Reference Manager on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure