From 6e0588f4cb26548344a33f8530ded631e7e85aaf Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Sat, 9 Jul 2022 11:28:32 +0200
Subject: start writing docs properly, not in the README

---
 doc/administration/installation.rst | 109 ++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 doc/administration/installation.rst

(limited to 'doc/administration/installation.rst')

diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst
new file mode 100644
index 0000000..b8ede06
--- /dev/null
+++ b/doc/administration/installation.rst
@@ -0,0 +1,109 @@
+Installation
+============
+
+This document will outline the installation process of Fietsboek, step-by-step.
+
+Creating an Environment
+-----------------------
+
+It is advised that you keep your Fietsboek installation in a separate `virtual
+environment <https://virtualenv.pypa.io/en/latest/>`__. This makes sure that
+the dependencies that Fietsboek pulls in do not interfere with your system's
+libraries, and it makes sure that you can upgrade those components easily
+without affecting other installed programs.
+
+We will assume that you create your environment in the ``.venv`` folder. Any
+path can be choosen, you just need to remember it for later
+
+.. code:: bash
+
+    # If Python 3 is the default on your system:
+    virtualenv .venv
+    # Otherwise:
+    virtualenv -p python3 .venv
+
+Installing the Python Modules
+-----------------------------
+
+The Python package manager takes care of installing all dependencies, all you
+need to do is tell it to install Fietsboek:
+
+.. code:: bash
+
+    # Assuming that we are in the Fietsboek folder
+    .venv/bin/pip install .
+    # Alternatively
+    .venv/bin/pip path/to/fietsboek/repository
+
+Optionally, you can install ``lxml``, which provides a faster XML parser to
+process the GPX files:
+
+.. code:: bash
+
+    .venv/bin/pip install lxml
+
+Configuring Fietsboek
+---------------------
+
+Before you can run Fietsboek, you need to adjust your configuration. See
+:doc:`configuration` for that.
+
+Setting up the Database
+-----------------------
+
+Fietsboek uses `alembic <https://alembic.sqlalchemy.org/en/latest/>`__ to
+manage the database scheme. To set up the initial database, run
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade head
+
+Adding an Administrator User
+----------------------------
+
+You can use the ``fietsctl`` command line program to add administrator users:
+
+.. code:: bash
+
+    .venv/bin/fietsctl -c production.ini useradd --admin
+
+Running Fietsboek
+-----------------
+
+To run Fietsboek, simply run
+
+.. code:: bash
+
+    .venv/bin/pserve production.ini
+
+.. warning::
+
+    It is strongly advised that you use a httpd configured with SSL as a
+    reverse proxy (such as `Apache2
+    <https://httpd.apache.org/docs/current/howto/reverse_proxy.html>`__ or
+    `nginx <https://nginx.org/en/docs/http/ngx_http_proxy_module.html>`__) to
+    handle external traffic to Fietsboek!
+
+    Fietsboek itself does not use SSL encryption for its traffic, and not
+    setting up a proper reverse proxy will put your user's data at risk!
+
+The default server uses `waitress
+<https://docs.pylonsproject.org/projects/waitress/en/stable/index.html>`__ and
+should be enough for small to medium traffic. It is implemented purely in
+Python and should run on most systems.
+
+Alternatively, you can switch to `gunicorn <https://gunicorn.org/>`__ or
+`mod_wsgi <https://modwsgi.readthedocs.io/en/master/>`__ for better
+performance. For those, refer to the Pyramid documentation for more information:
+
+* `gunicorn
+  <https://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gunicorn.html>`__
+* `mod_wsgi
+  <https://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/modwsgi/index.html>`__
+
+Maintaining Fietsboek
+---------------------
+
+A good installation should be well-oiled, which means it should be
+:doc:`updated <upgrading>` to new versions and :doc:`backups <backup>` should
+be done frequently.
-- 
cgit v1.2.3