Setup
=====

Requirements
------------

- `Python 3.12 <https://www.python.org>`_ or newer. It is likely that your
  system already comes with this. Otherwise, refer to the `Python Beginners
  Guide <https://wiki.python.org/moin/BeginnersGuide/Download>`_.

- A modern browser. **hircine** is built to target `ES2022
  <https://262.ecma-international.org/13.0>`_ and should run on all common
  browsers at the time of writing. See `this support table
  <https://caniuse.com/?feats=mdn-javascript_builtins_array_at,mdn-javascript_builtins_regexp_hasindices,mdn-javascript_builtins_object_hasown,mdn-javascript_builtins_error_cause,mdn-javascript_operators_await_top_level,mdn-javascript_classes_private_class_fields,mdn-javascript_classes_private_class_methods,mdn-javascript_classes_static_class_fields,mdn-javascript_classes_static_initialization_blocks>`_
  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
<packaging:creating and using virtual environments>`:

.. code-block:: console

   $ 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
<https://hircine.oriole.systems/dist/hircine-0.1.1-py3-none-any.whl>`_ and
install it using `pip <https://pip.pypa.io/en/stable/>`_:

.. code-block:: console

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

Now the ``hircine`` command is available from within your shell:

.. code-block:: console

   (.venv) $ hircine version
   hircine 0.1.1 "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 <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 :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 <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 <https://gunicorn.org>`_. 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.