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 :ref:`virtual environment `: .. code-block:: console $ python -m venv $ source /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 `_: .. code-block:: console (.venv) $ python -m pip install Now the ``hircine`` command is available from within your shell: .. code-block:: console (.venv) $ hircine version hircine 0.2.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: .. code-block:: console (.venv) $ cd (.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 :term:`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 ``. If ``-C `` 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``: .. code-block:: console (.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.