Installing eScriptorium on a Cloud Server (Debian 11) with a Fully Qualified Domain Name

System Requirements

To follow this guide, you should first create a cloud server with...

At least 2 CPU cores (a shared CPU plan should be fine to get started)
At least 4 GB of RAM
At least 20 GB of disk space
An IPv4 address
A fresh installation of Debian 11

Note

The below instructions have been tested on Hetzner's Shared vCPU server with an x86 processor with 2 vCPUs, 4 GB RAM, and 40 GB SSD. However, a shared CPU server may not be ideal for high or sustained workloads. (The author of this article is not affiliated with Hetzner in any way.)

Domain Requirements

In this guide, escriptorium.example.com is used as the FQDN for the eScriptorium site. As you go through this guide, replace this domain name with your own domain name.

Access the DNS records of your domain name.
Add an A record for escriptorium (or any other string) that points to the IPv4 address of the server where you plan to install eScriptorium.

Tip

If you don't have access to the DNS records of your domain name, ask your domain administrator to create a subdomain record to point to the IPv4 address of your server.

Before You Begin

You should

have access to a terminal application that supports SSH connections
know how to use SSH to sign in to a remote server
have basic Debian command line skills
know how to use a text editor in Debian (such as vi or nano)
have root access to the Debian server where you want to install eScriptorium (or login credentials for a non-root user with sudo permissions)
set aside at least 1 to 2 hours for this procedure

Step 1: Secure Your Cloud Server

Open the terminal application of your choice on your computer.
Locate the access credentials of the Debian server you have created (see System Requirements above).
From your terminal application, sign into the server as the root user, using the password or SSH key generated at the time of creating the server.

If you can't sign in to the server using SSH, it could mean that SSH connections are blocked. In that case, sign into your account with your hosting provider and access the server using the hosting provider's browser-based terminal. You can use your terminal application later on after enabling SSH.
Update the server.
```
apt update
apt upgrade
```
Install the firewall application (ufw).
```
apt install ufw
```
Ensure SSH is allowed.
```
ufw allow ssh
```
Enable the firewall after allowing SSH.
```
ufw enable
```
Create a non-root user. Replace htrfan with the username of your choice. And in the steps that follow, replace htrfan with the username you have created.
```
adduser htrfan
```
Generate a strong password when prompted by the adduser command, and save this password.
Give sudo permissions to the newly created non-root user.
```
usermod -aG sudo htrfan
```
From a new window or tab of your terminal application, access the server with an SSH connection using the sudo user account. Replace htrfan with your the username you have created, and 77.77.77.77 with the IP address of your server.

For password authentication:
```
ssh [email protected]
```
For key-based authentication (replace .\private-key with the location and filename of your private key):
```
ssh -i .\private-key [email protected]
```

Tip

For more rigorous hardening and securing, such as setting up key-based authentication for the non-root user and blocking malicious login attempts, see this guide on the Linux Handbook website.

Step 2: Install the Apache Web Server

Install the Apache web server.
```
sudo apt install apache2
```
Enter the password for the htrfan user when prompted by the sudo command.
The Apache server may be blocked by the firewall set up earlier. To open both port 80 (normal, unencrypted web traffic) and port 443 (TLS/SSL encrypted traffic), enter the following command:
```
sudo ufw allow 'WWW Full'
```
Restart the Apache server.
```
sudo service apache2 restart
```
Check the status of the Apache server.
```
sudo service apache2 status
```
Open a browser tab and go to the IP address of the server, for example, http://77.77.77.77. Replace 77.77.77.77 with the IP address of your server. You should see a page titled Apache2 Debian Default Page.

Make sure the browser does not redirect you to an HTTPS version of the IP address. This will not work as you have not yet set up HTTPS access.

Step 3: Install an HTTPS Certificate using Certbot

Install snapd
```
sudo apt install snapd
```
Remove any previously installed Certbot packages.
```
sudo apt remove certbot
```
Install Certbot
```
sudo snap install --classic certbot
```

Prepare the Certbot command

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Install a Certbot certificate. This will turn on HTTPS access.
```
sudo certbot --apache
```
Follow the prompts. When asked to enter the domain name for which you would like a certificate, carefully type in the domain name you have created (as per the Domain Requirements section above). For example, escriptorium.example.com.
Test automatic renewal of the Certbot certificate.
```
sudo certbot renew --dry-run
```
Test that the Certbot command worked. Open a browser tab and go to the HTTPS-enabled domain name, for example, https://escriptorium.example.com. You should once again see the Apache2 Debian Default Page.

Step 4: Enable Reverse Proxy

Create a new Apache configuration file for eScriptorium.

cd /etc/apache2/sites-available/

sudo vi escriptorium.conf

Copy the following content into the file.

# eScriptorium
<Location "/">
    ProxyPass "http://localhost:8000/"
    ProxyPassReverse "http://localhost:8000/"
    RequestHeader set X-Forwarded-Proto 'https' env=HTTPS
</Location>
<Location "/ws/notif/">
    ProxyPass "ws://localhost:8080/ws/notif/"
</Location>

Enable the Apache modules to set up a reverse proxy.

sudo a2enmod proxy proxy_http proxy_balancer lbmethod_byrequests

Restart Apache.
```
sudo service apache2 restart
```

Step 5: Install the Programs Required for eScriptorium

Note

These instructions are an edited version of the instructions from UB Mannheim.

Install the programs you need to install eScriptorium.

sudo apt install git postgresql postgresql-contrib libpq-dev redis-server gettext netcat-traditional jpegoptim pngcrush libvips build-essential python3 python3-dev python3-venv npm

If error messages appear during the PostgreSQL installation, enter the following commands.

``` 
 sudo apt update
 sudo apt update --fix-missing
 sudo apt install postgresql
 ```

Start the PostgreSQL and Redis servers.

sudo service postgresql start
sudo service redis-server start

Create a username for eScriptorium.

Decide if you want to use your Linux username as the eScriptorium username.

If yes, enter this command:
```
(cd /tmp && sudo -u postgres createuser --superuser $(whoami))
```
If you want a different username, enter the below command, replacing 'yourusername' with the name you choose.
```
sudo -u postgres createuser --superuser yourusername
```
Create a database for eScriptorium.
```
createdb escriptorium
```
Clone the eScriptorium repository from GitLab.
```
git clone https://gitlab.com/scripta/escriptorium.git ~/escriptorium
```
This command will clone the repository in your home folder, for example, /home/htrfan.
Go to the newly created escriptorium directory.

cd ~/escriptorium
Create and activate the virtual environment.

Enter the following commands.
```
python3 -m venv env
source env/bin/activate
pip install -U pip setuptools wheel
```
Install all the Python packages needed:
```
pip install -r app/requirements.txt -r app/requirements-dev.txt
```
This process can take a while. A good time for a break!

If you encounter an error related to conflict in dependencies, try to loosen the package version specified for Kraken in /app/requirements.txt. For example, change kraken==4.3.12 to kraken~=4.3.12.

Make your copy of the local_settings.py file.

cd $HOME/escriptorium/app/escriptorium
cp local_settings.py.example local_settings.py

Open the local_settings.py file with a text editor (such as vi), and add the below lines. Replace the domain name below with your domain for your eScriptorium instance.
```
DOMAIN = 'escriptorium.example.com'
CSRF_TRUSTED_ORIGINS = ['https://escriptorium.example.com']
```
Install the latest version of NPM.

Go to the front directory (which is in the escriptorium directory).
```
cd $HOME/escriptorium/front
```
```
sudo npm install -g n
sudo n latest
hash -r
npm install
```
If you see error messages, then you should run the following command. This should remove the critical errors. Other errors may persist, but you can ignore them for the time being.
```
npm audit fix
```

Step 6: Run eScriptorium

Run the command to run eScriptorium as a production instance.
```
npm run production
```

Check the installation.

cd ~/escriptorium/app
python manage.py check --settings escriptorium.local_settings

Create the SQL tables required.

python manage.py migrate --settings escriptorium.local_settings

Update the translations for the user interface.

python manage.py makemessages --all --settings escriptorium.local_settings
python manage.py compilemessages --settings escriptorium.local_settings

Open a new terminal window, and sign in with the sudo user account. Run a simple Celery worker in this terminal.
```
DJANGO_SETTINGS_MODULE=escriptorium.local_settings celery -A escriptorium worker -l INFO &
```
Start the server.

In the previously opened terminal, enter the below command.
```
python manage.py runserver --settings escriptorium.local_settings
```

With that, the essential installation steps are completed.

Important

Do not close the terminal window or stop the SSH connection. Keep the previous command running while you verify the installation.

Verify the Installation

Your instance of eScriptorium should now be available on your chosen domain name, for example, https://escriptorium.example.com. Open a browser tab and navigate to this domain.

If you see the eScriptorium landing page, success!

Caution

The first thing you should do on the eScriptorium site is change the admin username and password.

Sign in with the default username and password (admin, admin). Then, go to the profile settings of the admin user account and change the password.

Post Installation

Restarting eScriptorium from the Terminal

If you close the SSH connection, you won't be able to access the eScriptorium website.

If you want to use the website again, you should activate eScriptorium again via the terminal. This should be done every time you want to use the eScriptorium website.

    cd ~/escriptorium
    source env/bin/activate
    cd app
    sudo service postgresql start
    sudo service redis-server start
    DJANGO_SETTINGS_MODULE=escriptorium.local_settings celery -A escriptorium worker -l INFO &
    python manage.py runserver --settings escriptorium.local_settings

Then, open a browser tab and go to the URL of your eScriptorium instance.

A better option is to enable eScriptorium to run as a service, explained below.

Make eScriptorium Run as a Service

Go to the escriptorium/env/bin directory.
```
cd $HOME
cd escriptorium/env/bin
```
Create a file called run_escriptorium.sh
```
vi run_escriptorium.sh
```

Paste the below contents into file. Replace the instances of /home/htrfan/ with your home directory.

#!/bin/bash

source /home/htrfan/escriptorium/env/bin/activate
export DJANGO_SETTINGS_MODULE=escriptorium.local_settings
export ESC_LANGUAGES="de,en,fr"

export OMP_NUM_THREADS=1

cd /home/htrfan/escriptorium/app
celery --app escriptorium worker --concurrency 4 --loglevel DEBUG &
python -Wa manage.py runserver --settings escriptorium.local_settings

Make the script executable.
```
chmod 755 run_escriptorium.sh
```
Create a file called escriptorium.service in /etc/systemd/system/.
```
sudo vi /etc/systemd/system/escriptorium.service
```

Paste the below contents into file. Replace the instances of /home/htrfan/ with your home directory, and replace the definitions of User and Group as well.

[Unit]
Description=eScriptorium web application
After=network.target

[Service]
ExecStart=/home/htrfan/escriptorium/env/bin/run_escriptorium.sh
WorkingDirectory=/home/htrfan/escriptorium/app
Restart=on-failure
User=htrfan
Group=htrfan
Environment=TXS=xproduction

[Install]
WantedBy=multi-user.target

Provide feedback

Saved searches

Use saved searches to filter your results more quickly