Draft: Upenn rework

.gitignore

@@ -57,7 +57,6 @@ cover/
 
 # Django stuff:
 *.log
-local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
@@ -158,3 +157,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+/tmp/
+variables.env
+/ssh

Dockerfile

@@ -0,0 +1,92 @@
+FROM docker.io/library/node:12-alpine AS frontend
+
+RUN apk update && apk add git
+
+ENV ESCRIPTORIUM_SRC=/escriptorium-src
+RUN git clone https://gitlab.com/scripta/escriptorium.git ${ESCRIPTORIUM_SRC} && \
+    cd ${ESCRIPTORIUM_SRC} && \
+    git checkout develop
+
+RUN cp -r ${ESCRIPTORIUM_SRC}/front /build
+WORKDIR /build
+RUN npm ci && npm run production
+
+# Pull official base image
+FROM registry.gitlab.com/scripta/escriptorium/base:kraken529 AS escriptorium
+
+# try to autodetect number of cpus available
+# ENV NGINX_WORKER_PROCESSES auto
+
+ARG VERSION_DATE="passthistobuildcmd"
+ENV VERSION_DATE=$VERSION_DATE
+ENV FRONTEND_DIR=/usr/src/app/front
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+ENV ESCRIPTORIUM_SRC=/escriptorium-src
+COPY --from=frontend ${ESCRIPTORIUM_SRC} ${ESCRIPTORIUM_SRC}
+
+# set work directory
+WORKDIR /usr/src/app
+
+RUN cp ${ESCRIPTORIUM_SRC}/app/entrypoint.sh /usr/src/app/entrypoint.sh && \
+    cp ${ESCRIPTORIUM_SRC}/app/manage.py /usr/src/app/manage.py && \
+    cp ${ESCRIPTORIUM_SRC}/app/requirements.txt /usr/src/app/requirements.txt && \
+    cp ${ESCRIPTORIUM_SRC}/app/uwsgi.ini /usr/src/app/uwsgi.ini && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/apps /usr/src/app/apps && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/escriptorium /usr/src/app/escriptorium && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/locale /usr/src/app/locale && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/homepage /usr/src/app/homepage && \
+    rm -rf ${ESCRIPTORIUM_SRC}
+COPY --from=frontend /build/dist /usr/src/app/front
+
+WORKDIR /usr/src/app
+
+COPY ./escriptorium/local_settings.py /usr/src/app/escriptorium/local_settings.py
+RUN chmod 644 /usr/src/app/escriptorium/local_settings.py
+
+# We want to replicate PU CDH's Ansible tasks for eScriptorium:
+#
+#   https://github.com/Princeton-CDH/cdh-ansible/blob/013fd75dfa9c857d025b97b02c95e2072166264a/roles/escriptorium_setup/tasks/main.yml
+#
+# They ensure eScriptorium will use the htr2hpc module for model and segmentation training. Specifically, they:
+#
+# 1. rename the train and segtrain functions in tasks.py to es_train and es_segtrain
+# 2. import segtrain and train functions from htr2hpc.tasks
+
+# rename the train and segtrain functions in tasks.py
+ENV TASKS_FILE=/usr/src/app/apps/core/tasks.py
+RUN sed -E -i 's/^( *)def segtrain/\1def es_segtrain/' ${TASKS_FILE}
+RUN sed -E -i 's/^( *)def train/\1def es_train/' ${TASKS_FILE}
+
+# Import the functions htr2hpc.tasks module just above "@shared_task...\ndef es_segtrain..."
+RUN line_number=$(($(grep -n "^ *def es_segtrain" ${TASKS_FILE} | cut -d: -f1) - 1)) && \
+    echo "${line_number}" | grep -q "^[0-9][0-9]*$" && \
+    sed -i "${line_number}i from htr2hpc.tasks import segtrain, train" ${TASKS_FILE} && \
+    sed -i "${line_number}i # EDITED BY pennlib-escritorium Dockerfile" ${TASKS_FILE}
+
+#     - name: Expose read-write training accuracy model field in API
+# see: the ansible task referenced above
+ENV SERIALIZERS_PY=/usr/src/app/apps/api/serializers.py
+RUN sed -E -i "s/'accuracy_percent', 'rights',/'accuracy_percent', 'training_accuracy', 'rights',/" ${SERIALIZERS_PY}
+
+# Add htr2hpc to requirements.txt and run `pip install`
+# for local development just add this project as ./
+RUN mkdir /htr2hpc
+COPY src/ /htr2hpc/src/
+RUN ls /htr2hpc/
+COPY pyproject.toml /htr2hpc/
+COPY README.md /htr2hpc/
+RUN echo  >> requirements.txt
+RUN echo '/htr2hpc/' >> requirements.txt
+RUN pip --no-cache-dir install --root-user-action ignore -r requirements.txt
+
+# Change the django port; configure processes
+COPY ./escriptorium/uwsgi.ini /usr/src/app/
+RUN chmod 644 /usr/src/app/uwsgi.ini
+
+# update entry point to set the site based on ESCRIPTORIUM_HOST
+COPY ./escriptorium/entrypoint.sh /usr/src/app/
+RUN chmod 755 /usr/src/app/entrypoint.sh
+
+ENTRYPOINT ["/usr/src/app/entrypoint.sh"]

Dockerfile.portainer

@@ -0,0 +1,88 @@
+FROM docker.io/library/node:12-alpine AS frontend
+
+RUN apk update && apk add git
+
+ENV ESCRIPTORIUM_SRC=/escriptorium-src
+RUN git clone https://gitlab.com/scripta/escriptorium.git ${ESCRIPTORIUM_SRC} && \
+    cd ${ESCRIPTORIUM_SRC} && \
+    git checkout tags/dev-0.14.2
+
+RUN cp -r ${ESCRIPTORIUM_SRC}/front /build
+WORKDIR /build
+RUN npm ci && npm run production
+
+# Pull official base image
+FROM registry.gitlab.com/scripta/escriptorium/base:kraken529 AS escriptorium
+
+# try to autodetect number of cpus available
+# ENV NGINX_WORKER_PROCESSES auto
+
+ARG VERSION_DATE="passthistobuildcmd"
+ENV VERSION_DATE=$VERSION_DATE
+ENV FRONTEND_DIR=/usr/src/app/front
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+ENV ESCRIPTORIUM_SRC=/escriptorium-src
+COPY --from=frontend ${ESCRIPTORIUM_SRC} ${ESCRIPTORIUM_SRC}
+
+# set work directory
+WORKDIR /usr/src/app
+
+RUN cp ${ESCRIPTORIUM_SRC}/app/entrypoint.sh /usr/src/app/entrypoint.sh && \
+    cp ${ESCRIPTORIUM_SRC}/app/manage.py /usr/src/app/manage.py && \
+    cp ${ESCRIPTORIUM_SRC}/app/requirements.txt /usr/src/app/requirements.txt && \
+    cp ${ESCRIPTORIUM_SRC}/app/uwsgi.ini /usr/src/app/uwsgi.ini && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/apps /usr/src/app/apps && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/escriptorium /usr/src/app/escriptorium && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/locale /usr/src/app/locale && \
+    cp -r ${ESCRIPTORIUM_SRC}/app/homepage /usr/src/app/homepage && \
+    rm -rf ${ESCRIPTORIUM_SRC}
+COPY --from=frontend /build/dist /usr/src/app/front
+
+WORKDIR /usr/src/app
+
+COPY local_settings.py /usr/src/app/escriptorium/local_settings.py
+RUN chmod 644 /usr/src/app/escriptorium/local_settings.py
+
+# We want to replicate PU CDH's Ansible tasks for eScriptorium:
+#
+#   https://github.com/Princeton-CDH/cdh-ansible/blob/013fd75dfa9c857d025b97b02c95e2072166264a/roles/escriptorium_setup/tasks/main.yml
+#
+# They ensure eScriptorium will use the htr2hpc module for model and segmentation training. Specifically, they:
+#
+# 1. rename the train and segtrain functions in tasks.py to es_train and es_segtrain
+# 2. import segtrain and train functions from htr2hpc.tasks
+
+# rename the train and segtrain functions in tasks.py
+ENV TASKS_FILE=/usr/src/app/apps/core/tasks.py
+RUN sed -E -i 's/^( *)def segtrain/\1def es_segtrain/' ${TASKS_FILE}
+RUN sed -E -i 's/^( *)def train/\1def es_train/' ${TASKS_FILE}
+
+# Import the functions htr2hpc.tasks module just above "@shared_task...\ndef es_segtrain..."
+RUN line_number=$(($(grep -n "^ *def es_segtrain" ${TASKS_FILE} | cut -d: -f1) - 1)) && \
+    echo "${line_number}" | grep -q "^[0-9][0-9]*$" && \
+    sed -i "${line_number}i from htr2hpc.tasks import segtrain, train" ${TASKS_FILE} && \
+    sed -i "${line_number}i # EDITED BY pennlib-escritorium Dockerfile" ${TASKS_FILE}
+
+#     - name: Expose read-write training accuracy model field in API
+# see: the ansible task referenced above
+ENV SERIALIZERS_PY=/usr/src/app/apps/api/serializers.py
+RUN sed -E -i "s/'accuracy_percent', 'rights',/'accuracy_percent', 'training_accuracy', 'rights',/" ${SERIALIZERS_PY}
+
+# Add htr2hpc to requirements.txt and run `pip install`
+RUN cp requirements.txt requirements.txt.bak
+COPY extra_requirements.txt /usr/src/app/extra_requirements.txt
+RUN cat requirements.txt.bak extra_requirements.txt | sort | uniq > requirements.txt
+RUN rm requirements.txt.bak extra_requirements.txt
+RUN pip --no-cache-dir install --root-user-action ignore -r requirements.txt
+
+# Change the django port; configure workers
+COPY uwsgi.ini /usr/src/app/
+RUN chmod 644 /usr/src/app/uwsgi.ini
+
+# update entry point to set the site based on ESCRIPTORIUM_HOST
+COPY entrypoint.sh /usr/src/app/
+RUN chmod 755 /usr/src/app/entrypoint.sh
+
+ENTRYPOINT ["/usr/src/app/entrypoint.sh"]

README.md

@@ -18,7 +18,7 @@ The project goal is integrating the [eScriptorium handwritten text recognition (
 This package can be installed directly from GitHub using `pip`:
 
 ```console
-pip install git+https://github.com/Princeton-CDH/htr2hpc.git@main#egg=htr2hpc
+pip install git+https://github.com/upenn-libraries/htr2hpc.git@main#egg=htr2hpc
 ```
 
 [`pucas`](https://github.com/Princeton-CDH/django-pucas) is a dependency of this package and will be included when you install this package.

README_Docker.md

@@ -0,0 +1,177 @@
+# htr2hpc docker
+
+Penn Libraries' htr2hpc provides Dockerfile and docker-compose files for development and portainer deployments of eScriptorium with htr2hpc.
+
+The Dockerfile and docker compose configurations automate the installation steps in the [README](README.md) and [Princeton CDH's Ansible playbook](https://github.com/Princeton-CDH/cdh-ansible/blob/main/playbooks/escriptorium.yml).
+
+This file provides instructions for docker deployment in development and on portainer.
+
+## GPC installation for development and portainer deployment
+
+HTR2HPC is both a django application that integrates with eScriptorium and a command-line application `htr2hpc-train` that is run on the HPC cluster. Both pieces must be installed and operating. For instructions on installing `htr2hpc-train` on the GPC see the [training README](src/htr2hpc/train/README.md). 
+
+## Development deployment
+
+Copy `variables.env_example` to `variables.env` and edit it to match your environment. See "Configuration variables" for more information.
+
+```bash
+cp  variables.env_example variables.env
+```
+
+Create an SSH key.
+
+```bash
+$ mkdir ssh
+$ ssh-keygen -N "" -f ./ssh/htr2hpc_ed25519 -t ed25519
+$ ls ssh
+htr2hpc_ed25519     htr2hpc_ed25519.pub
+```
+
+Add the `./ssh/htr2hpc_id_rsa.pub` public key to the `${HOME}/.ssh/authorized_keys` file on the HPC cluster. See "SSH key authentication" below for more information.
+
+Then build and run:
+
+```bash
+docker compose build --no-cache
+docker compose up
+# or, if you don't want to see the logs:
+# docker compose up -d
+```
+
+eScriptorium should be available at http://localhost:8080. Use the admin username and password from `variables.env`.
+
+### To clear everything out and start over:
+
+```bash
+docker compose down
+docker volume rm $(docker volume ls -q -f name=htr2hpc)
+docker compose build --no-cache
+docker compose up
+```
+
+Or, if you prefer one line:
+
+```bash
+docker compose down && docker volume rm $(docker volume ls -q -f name=htr2hpc) && docker compose build --no-cache && docker compose up
+```
+
+Or, more thorough:
+
+```bash
+docker compose down -v --remove-orphans && docker container prune -f && { [[ -n "$(docker volume ls -q -f name=htr2hpc)" ]] && docker volume rm -f $(docker volume ls -q -f name=htr2hpc) || docker compose build --no-cache && docker compose up; }
+```
+
+### Configuration variables
+
+For model training in development you'll need to edit the variables: `ESCRIPTORIUM_HOST`, `HPC_SSH_USER`, and `HPC_WORKING_DIR`. `ESCRIPTORIUM_HOST` should be set to the protocol, local machine public IP, and nginx port; e.g., http://1.2.3.4:8080.
+
+NOTE: I haven't been able to get training to work from my laptop. (de 2025-08-22)
+
+```shell
+ESCRIPTORIUM_HOST=example.com  # The host escriptorium is running on
+HPC_HOSTNAME=hpc.host.edu      # The hostname of the HPC cluster
+HPC_SSH_USER=uername           # Username if one account is used for training
+```
+
+### SSH key authentication
+
+htr2hpc relies on ssh secure authentication to run slurm jobs on the HCP cluster. By default, the key is expected at `./ssh/htr2hpc_ed25519`.
+
+The development docker compose file maps local `./ssh` to `/usr/src/app/.ssh` in the docker container.
+
+```
+# docker-compose.yml
+x-app:
+  # ...
+  volumes:
+    - ./ssh:/usr/src/app/.ssh
+```
+
+_**IMPORTANT: Do not check the ssh key into version control!**_
+
+The directory `./ssh` is in the `.gitignore` file and, thus, will ignored by git commands. If you put the ssh key in another directory in this project, make sure it is not checked into version control.
+
+## What this repository does
+
+This repo provides a docker deployment that builds a custom instance of eScriptorium with the Penn Libraries fork of htr2hpc and runs it in a docker compose environment.
+
+The deployment is based on the htr2hpc installation instructions and the Princeton-CDH Ansible deployment scripts, https://github.com/Princeton-CDH/cdh-ansible/
+
+Useful links:
+
+- [eScriptorium playbook](https://github.com/Princeton-CDH/cdh-ansible/blob/main/playbooks/escriptorium.yml)
+- [Staging variables](https://github.com/Princeton-CDH/cdh-ansible/blob/main/inventory/group_vars/htr_staging/vars.yml)
+- [escriptorium_setup tasks](https://github.com/Princeton-CDH/cdh-ansible/blob/main/roles/escriptorium_setup/tasks/main.yml)
+
+The `docker-compose.yml` file is adapted from the official eScriptorium repository (https://gitlab.com/scripta/escriptorium). It changes the service configurations for the `app` and `nginx` services to use locally built images, `pennlib-escriptorium` and `pennlib-escriptorium-nginx`, respectively.
+
+The `pennlib-escriptorium` image is built from `./Dockerfile`. It pulls the latest eScriptorium image, then
+
+- adds the `escriptorium/local_settings.py` file, which imports the htr2hpc module
+- modifies the `requirements.txt` file to include the htr2hpc module, 
+- add the `escriptorium/uwsgi.ini` custom web server configuration, and
+- runs `pip install` to install the htr2hpc module.
+
+The `pennlib-escriptorium-nginx` image is built from `./nginx/Dockerfile`. It replaces the original nginx image, `registry.gitlab.com/scripta/escriptorium/nginx:latest`, which is two years old and does not include the eScriptorium proxy configuration.
+
+**TODO**: The docker-compose.yml file still refers to `registry.gitlab.com/scripta/escriptorium/mail`, which, like the nginx image, is two years old. It may need to be replaced as well.
+
+## Portainer
+
+Use `Dockerfile.portainer`, `nginx/Dockerfile`, `docker-compose.portainer.yml`, and `variables.env.portainer_example` for Portainer deployments.
+
+The steps for deployment are these:
+
+1. Build the htr2hpc image
+2. Build the htr2hpc-nginx image
+3. Create the stack using `docker-compose.portainer.yml` and edited `variables.portainer`
+
+**(1) Build the HTR2HPC image**
+
+Build htr2hpc image on portainer using `Dockerfile.portainer`. 
+
+On the Images > Build Image page:
+
+   - Name the image `htr2hpc`
+   - Paste the content of `Dockerfile.portainer` into the Web Editor
+   - Upload the files from `./escriptorium`: `entrypoint.sh, extra_requirements.txt, local_settings.py, uwsgi.ini`
+   - Build the image
+
+**(2) Build the HTR2HPC Nginx image**
+
+On the Images > Build Image page:
+
+- Name the image `htr2hpc-nginx`
+- Paste the content of `nginx/Dockerfile` into the Web Editor
+- Upload the file `nginx.conf` from `./nginx`
+- Build the image
+
+**(3) Create the stack**
+
+On the 'Stacks > Add stack' page
+
+- Name the stack: `htr2hpc`
+- Paste the content of `docker-compose.portainer.yml` in the web editor box
+- Click on 'Advanced mode' under Environments variables and paste in the content `variables.portainer`
+- Edit the environment variables 
+- Click 'Deploy the stack' 
+
+If this is the initial setup, the private SSH key file should be added to the volume `ssh`. This can be done by bashing into the web container and creating a private key file in `/usr/src/app/.ssh`. In the default configuration this is an ed25519 key named `htr2hpc_ed25519` 
+
+### Trobleshooting
+
+#### Bad gateway
+
+Bad gateway errors can arise for a couple of reasons.
+
+1. The web (django) container has not completely started. Check the log for web container and look for the notice that the wsgi workers have been spawned
+
+   - ```*** uWSGI is running in multiple interpreter mode ***
+      spawned uWSGI master process (pid: 1)
+      spawned uWSGI worker 1 (pid: 75, cores: 1)
+      spawned uWSGI worker 2 (pid: 76, cores: 1)
+      spawned uWSGI worker 3 (pid: 77, cores: 1)
+      spawned uWSGI worker 4 (pid: 78, cores: 1)
+      spawned uWSGI http 1 (pid: 79)
+      ```
+2. The web container has been redeployed and assigned an IP not known to the nginx server. Try restarting nginx.