Setup

Requirements

  • Python 3.12 or newer. It is likely that your system already comes with this. Otherwise, refer to the Python Beginners Guide.

  • A modern browser. hircine is built to target ES2022 and should run on all common browsers at the time of writing. See this support table for a detailed breakdown. The web interface was successfully tested on the following systems and browsers:

    • Linux 6.7.6: Firefox 123.0

    • Windows 10 Pro 22H2: Edge 122.0.2365.59, Firefox 123.0

    • Windows 11 Pro 23H2: Edge 122.0.2365.59, Firefox 123.0

hircine is designed to be hosted on Linux systems but may be set up for Windows as well. Keep in mind that some utilities (e.g. gunicorn) are not available for Windows.

Installation

hircine should be installed in a virtual environment:

$ python -m venv <VENVDIR>
$ source <VENVDIR>/bin/activate

Note

VENVDIR should only ever contain program files and should not be the directory you choose for the database in the next step.

For example, ~/.local/share/hircine is a sensible setting for VENVDIR.

Once the environment is set up, download the latest wheel and install it using pip:

(.venv) $ python -m pip install <WHEEL>

Now the hircine command is available from within your shell:

(.venv) $ hircine version
hircine 0.3.0 "Satanic Satyr"

Important

Outside of this document it is assumed that the virtual environment is activated and that the hircine command is present.

Initializing the database

Next, navigate to where you want to store the database and initialize it:

(.venv) $ cd <DIR>
(.venv) $ hircine init

This will create the following structure:

Item

Description

hircine.db

the SQLite database

content/

the directory containing your archives (may be nested arbitrarily)

objects/

the object store for processed images

backups/

backups of the SQLite database

Tip

By default, the command-line interface and the web application will always look for the database in the current directory. Whilst this behaviour cannot be changed when launching the web application, you may direct the command-line program to a different directory using -C <DIR>.

If -C <DIR> is given on the command line, it must appear before any sub-command (import, etc.)

Starting the web application

To serve the web application, you need a compatible ASGI server. We recommend gunicorn. The endpoint for the web application is the app() factory in hircine.app:

(.venv) $ python -m pip install gunicorn
(.venv) $ gunicorn -k uvicorn.workers.UvicornWorker --bind localhost:8000 "hircine.app:app()"

Now you can point your browser to http://localhost:8000 to open the web application. To stop it, simply terminate gunicorn or the ASGI server of your choice.