1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
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.3.0-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.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:
.. 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.
|
