start writing docs properly, not in the README

4 files changed, 303 insertions, 0 deletions

diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
new file mode 100644
index 0000000..9566e38
--- /dev/null
+++ b/doc/administration/backup.rst
@@ -0,0 +1,61 @@
+Backup & Restore
+================
+
+A well-maintained Fietsboek instance should have regular backups configured in
+case data is lost due unforseen reasons.
+
+.. note::
+
+    As a rule of thumb: A backup that you haven't restored is not a backup!
+
+    Part of the backup process is to ensure that the backups actually contain
+    the necessary data and that the restoration process works. Make sure to
+    test your backups on a separate installation of Fietsboek.
+
+Backup
+------
+
+All of the Fietsboek data is contained in the database. You should refer to the
+manual of your DBMS to see what the procedure for a backup is. Using the
+preferred way for your DBMS ensures that your backup represents a consistent
+state of the database.
+
+In addition to the actual data, you should also note down the Fietsboek version
+and the database schema version, as backups can only be restored to the same
+version!
+
+To view the fietsboek version in case you are using ``git``, you can use the
+following command:
+
+.. code:: bash
+
+    git rev-parse HEAD
+
+To view the database schema version, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c development.ini current
+
+Note those value in addition to your backup.
+
+Restore
+-------
+
+The restoration process works in three steps:
+
+First, we ensure that we are on the correct Fietsboek version. If you are using
+``git``, this can be done with ``git checkout``:
+
+.. code:: bash
+
+    git checkout NOTED_GIT_VERSION_HERE
+
+Then, we get the database schema to the right version:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade NOTED_ALEMBIC_VERSION_HERE
+
+Finally, we can restore the data. This step is dependent on the DBMS that you,
+therefore you should consult its documentation.
diff --git a/doc/administration/configuration.rst b/doc/administration/configuration.rst
new file mode 100644
index 0000000..48afde1
--- /dev/null
+++ b/doc/administration/configuration.rst
@@ -0,0 +1,66 @@
+Configuration
+=============
+
+The main configuration of Fietsboek is done via ``.ini``-files. By default,
+three such files exist:
+
+* ``production.ini`` contains the configuration for the production environment.
+  It turns off debugging features (as they are a security risk!) and should
+  contain the URL of the production database. This is the main file you want to
+  use if you just want to deploy Fietsboek.
+* ``development.ini`` contains the configuration for local development on
+  Fietsboek. **This should not be used for production purposes, as it provides
+  debugging information that poses a security risk!**
+* ``testing.ini`` contains the configuration that the automated tests will use.
+
+Most of the configuration is in the ``[app:main]`` category and looks like this:
+
+.. code:: ini
+
+    [app:main]
+    use = egg:fietsboek
+
+    pyramid.reload_templates = false
+    pyramid.debug_authorization = false
+    pyramid.debug_notfound = false
+    pyramid.debug_routematch = false
+    pyramid.default_locale_name = en
+
+    email.from = fietsboek@kingdread.de
+    email.smtp_url = debug://localhost:1025
+
+    available_locales = en de
+    enable_account_registration = true
+
+    session_key = <EDIT THIS>
+
+    sqlalchemy.url = sqlite:///%(here)s/fietsboek.sqlite
+
+    retry.attempts = 3
+
+* You should leave the ``use``, ``pyramid.reload_templates`` and
+  ``pyramid.debug_*`` settings as they are.
+* ``pyramid.default_locale_name`` can be used to set the default language of
+  the installation. Note that Fietsboek will try to detect the user's language,
+  so the ``default_locale_name`` is used as a fallback.
+* ``available_locales`` sets the list of available languages. Currently,
+  Fietsboek ships with English ("en") and German ("de"). Removing a language
+  from this list will make it unavailable. If you create a custom language
+  locally, make sure to add it to this list here!
+* ``enable_account_registration`` can be used to enable and disable the
+  creation of new accounts via the web interface, for example if you want to
+  have a private instance. New accounts can always be created using the CLI
+  management tool.
+* ``email.from`` sets the sender of emails, for example for account verifications.
+* ``email.smtp_url`` sets the URL of the SMTP server. The following formats are accepted:
+
+  * ``debug://`` a debug implementation that simply prints emails to the
+    standard output. Should not be used in production, as no emails would ever
+    arrive.
+  * ``smtp://host:port`` use the given SMTP server (without transport encryption!)
+  * ``smtp+ssl://host:port`` use the given SMTP server over a SSL connection
+  * ``smtp+starttls://host:port`` use the given SMTP server and the STARTTLS
+    command to start an encrypted channel.
+
+* ``email.username`` and ``email.password`` can be used to set the login
+  information for the SMTP server.
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.
diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst
new file mode 100644
index 0000000..4bdc656
--- /dev/null
+++ b/doc/administration/upgrading.rst
@@ -0,0 +1,67 @@
+Upgrading
+=========
+
+Fietsboek does not currently have an automated updater, however it is quite
+simple to update Fietsboek manually.
+
+.. warning::
+
+    Make sure to have backups of your user data ready in case the upgrade fails!
+
+.. note::
+
+    It is advised to stop the Fietsboek server during the backup process.
+
+Pulling the New Code
+--------------------
+
+First, we need to pull the new code. This step depends on the source that you
+have installed Fietsboek from. In the case that you use ``git``, this can be
+done in the following way:
+
+.. code:: bash
+
+    git pull
+    git checkout v42.0  # Put in the version that you want to update to here
+
+If you have downloaded an archive with the Fietsboek source, you need to
+download the archive with the new version and extract it somewhere.
+
+Installing the Python Module
+----------------------------
+
+Use ``pip`` to install the new version of the Fietsboek package, as well as any
+new additional dependencies:
+
+.. code:: bash
+
+    .venv/bin/pip install .
+
+This step is similar to the command that you used when installing Fietsboek
+initially.
+
+Note that removed dependencies are not automatically removed. It might be worth
+to start with a clean virtual environment from time to time to clear out old
+cruft.
+
+Upgrading the Database
+----------------------
+
+.. warning::
+
+   It cannot be stressed enough that you should have backups of your data. This
+   is your last chance.
+
+Some updates might change the database schema. Those updates come with database
+migrations that can adapt an existing database to the new schema. In order to
+do so, use ``alembic``:
+
+.. code:: bash
+
+    .venv/bin/alembic -c production.ini upgrade head
+
+Restarting Fietsboek
+--------------------
+
+You can now run Fietsboek again. This step depends on the method that you use
+to deploy Fietsboek.