diff options
Diffstat (limited to 'docs/setup.rst')
| -rw-r--r-- | docs/setup.rst | 113 |
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. |