From d1d654ebac2d51e3841675faeb56480e440f622f Mon Sep 17 00:00:00 2001
From: Wolfgang Müller
Date: Tue, 5 Mar 2024 18:08:09 +0100
Subject: Initial commit

---
 docs/setup.rst | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 docs/setup.rst

(limited to 'docs/setup.rst')

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.
-- 
cgit v1.2.3-2-gb3c3