summaryrefslogtreecommitdiffstatshomepage
path: root/docs/setup.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/setup.rst113
1 files changed, 113 insertions, 0 deletions
diff --git a/docs/setup.rst b/docs/setup.rst
new file mode 100644
index 0000000..ad2123e
--- /dev/null
+++ b/docs/setup.rst
@@ -0,0 +1,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.1.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.1.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.