Running eScriptorium on a Mac

Introduction

Many of the partners that we work with in RDDS need to extract machine-readable text from document images. Some general-purpose solutions like Google Vision or ABBY FineReader don't offer a way to improve the model.  You get what you get. It's understandable then, that people are really excited by eScriptorium, which gives you a nice interface to correct errors and to fine-tune handwriting recognition models. This is especially helpful when you're working with a specific set of documents with a common author or style of handwriting. 

The developers behind eScriptorium made an understandable decision not to host the application. Instead, they allow users to run the application themselves, either on a server or on their local computer. RDDS supports eScriptorium on a virtual machine. This is very useful for segmentation and transcription, but is currently insufficient for model training. We're working to find ways to connect our eScriptorium server with high-performance computing resources on campus, but for the moment, the best option is to train models locally on your own computer. Many recent MacBooks have a powerful CPU that is fully sufficient for most training tasks.  

This short tutorial shows how to run eScriptorium locally on a Mac. Kraken, the software eScriptorium uses to train new models, does not currently support Windows (but can be run in WSL). 

Instructions to Install and Run eScriptorium on a Mac

Install Docker

The simplest way to run eScriptorium is to use a virtualization program called Docker. 

• To install Docker, follow this link. If you have a newer Mac with a silicon "M" chip (you can check this in "About this Mac"), click on "Docker Desktop for Mac with Apple silicon." Otherwise, click on "Docker Desktop for Mac with Intel chip."
• Double-click Docker.dmg to open the installer, then drag the Docker icon to the Applications folder.
• Double-click Docker (a whale with little containers on it) in the Applications folder to start Docker.

Install HomeBrew

• Next, you will need to install a program called Homebrew.
  • Open the Terminal application

  • Paste the following command into the Terminal window and press Enter

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    

Install Git

• With homebrew installed, you can now install git, which is a program for sharing and versioning code. In the Terminal window, paste the following command and press Enter:

  brew install git
  

Clone the eScriptorium Repository

From here, we'll follow the instructions from eScriptorium, which can be found here.

• In the Terminal window, navigate to the directory where you want to install eScriptorium. For example, if you want to install it in your Documents folder, type the following command and press Enter:

  cd ~/Documents
   

`cd` stands for "change directory."

• Now enter the following command and press Enter:

  git clone https://gitlab.com/scripta/escriptorium.git
  

This will create a folder called "escriptorium" in your Documents folder and download the code for eScriptorium.
 

• Next enter the following command and press Enter:
   

  cd escriptorium && cp variables.env_example variables.env  

This will create a file called "variables.env" in the escriptorium folder.

If you want to inspect the file you can type: 

open variables.env

This file contains settings for your local eScriptorium installation. You can change these settings, but the default settings should work fine. Note that the default login information is username `admin` and password `admin`. 
 

DJANGO_SU_NAME=admin
DJANGO_SU_EMAIL=admin@admin.com
DJANGO_SU_PASSWORD=admin

• You're now ready to install eScriptorium. Enter the following command in the terminal and press Enter:

  docker compose pull
  

This will download the components ("images") needed to run the eScriptorium application.
 

•  To start eScriptorium, enter the following command and press Enter:

  docker compose up -d 
  

You will need to wait about five minutes for the application to start and be ready to use.

•  Next, open your web browser and go to http://localhost:8000. You should see the eScriptorium login page. Enter the username and password from the variables.env file (default username is `admin` and default password is `admin`). You should now be logged in to eScriptorium.
• You may need to export your image files and transcriptions from the escriptorium.pennds.org site. You can do this by going to the "Export" tab on the left side of the page. You can then import these files into your local eScriptorium installation by going to the "Import" tab on the left side of the page.
•  You can now train models using your local laptop or desktop computer.

• When you are done using eScriptorium, you can stop the application by entering the following command and pressing Enter:

  docker compose down
  

  or press the stop button in the Docker Desktop application.

• To restart it in the future, go to the Docker Desktop application and click on the "eScriptorium" container. Then click on the "Start" button. You can then go to http://localhost:8000 in your web browser to access eScriptorium. Alternatively, you can enter the following command in the Terminal window and press Enter:

  docker compose up -d