Installation on macOS

Installation on macOS

Preconditions

The installation on macOS needs some additional tools which are provided by Homebrew for example. Get Homebrew using this command:

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

Then install the additional tools:

brew install node openssl postgresql redis vips

Check the status of the postgresql and redis services:

brew services

Both services should have the status "started", otherwise start them now:

brew services start postgresql
brew services start redis

and check the status again.

Get the source code

Get the latest source code from GitLab and install it in your HOME directory:

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

Install Python and Python modules

macOS already provides Python 3.9 which can be used for eScriptorium as part of the Command Line Developer Tools. If those tools are not already installed (/usr/bin/python3 --version shows error message), those tools should be installed first:

xcode-select --install

If Python 3.9 still does not work, running this command should help:

sudo xcode-select --switch /Library/Developer/CommandLineTools

Then create a virtual Python environment and activate it:

/usr/bin/python3 -m venv $HOME/venv3.9
source $HOME/venv3.9/bin/activate

Update / install some basic Python packages:

pip install -U pip setuptools wheel

Install the required Python packages:

# Currently pyvips needs special handling.
pip install --debug --use-pep517 pyvips~=2.1.12
export CPPFLAGS="-I$(brew --prefix)/opt/openssl@3/include"
export LDFLAGS="-L$(brew --prefix)/opt/openssl@3/lib"
pip install -r $HOME/escriptorium/app/requirements.txt

Unless the development mode is disabled later in the local settings, some additional packages are required:

pip install -r $HOME/escriptorium/app/requirements-dev.txt

Install Node packages

Get the Node modules and build the local code using these commands:

cd $HOME/escriptorium/front
npm install
# Optionally run the following command to fix security issues.
npm audit fix
npm run build

Final installation steps

createdb escriptorium
cd $HOME/escriptorium/app

# Copy the local settings. Optionally edit them for example to disable the development mode.
cp escriptorium/local_settings.py{.example,}

python manage.py check --settings escriptorium.local_settings
python manage.py migrate --settings escriptorium.local_settings

Run eScriptorium

Activate the virtual Python environment if it is not still active:

source $HOME/venv3.9/bin/activate

Run the worker process and the web application:

export DJANGO_SETTINGS_MODULE=escriptorium.local_settings
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
export OMP_NUM_THREADS=1
cd $HOME/escriptorium/app
celery -A escriptorium worker --concurrency 4 --loglevel DEBUG &
python manage.py runserver --settings escriptorium.local_settings

Now connect your web browser to http://localhost:8000/ and login with username and password admin.

Using GPU

Latest pytorch supports accelerated training (see pytorch documentation), but does not implement all operators which are used by kraken. At least the implementation of aten::_ctc_loss is still missing (see related issue). Mixing the GPU and and the CPU is possible, but much slower than using only the CPU. Therefore segmentation, recognition and training only run on the CPU with macOS.

Alternate installation on macOS with podman

Run Debian with podman:

podman run -ti --name escriptorium docker.io/debian:bookworm-slim

Upgrade installed packages and install package sudo:

apt update
apt upgrade
apt install sudo

Continue the installation by following the instructions for Linux.