aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile20
-rw-r--r--doc/administration/backup.rst61
-rw-r--r--doc/administration/configuration.rst66
-rw-r--r--doc/administration/installation.rst109
-rw-r--r--doc/administration/upgrading.rst67
-rw-r--r--doc/conf.py60
-rw-r--r--doc/index.rst46
-rw-r--r--doc/make.bat35
8 files changed, 464 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
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.
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..e7f04e0
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Fietsboek'
+copyright = '2022, Daniel Schadt'
+author = 'Daniel Schadt'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3', None),
+ 'pyramid': ('https://docs.pylonsproject.org/projects/pyramid/en/latest/', None),
+ 'sqlalchemy': ('https://docs.sqlalchemy.org/en/14/', None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..05449cd
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,46 @@
+.. Fietsboek documentation master file, created by
+ sphinx-quickstart on Thu Jun 30 20:46:28 2022.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to Fietsboek's documentation!
+=====================================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ administration/installation
+ administration/configuration
+ administration/upgrading
+ administration/backup
+
+Fietsboek is a self-hostable sharing site for GPX track recordings with social
+features. The goal is to have an application like `MyTourbook
+<https://mytourbook.sourceforge.io/mytourbook/>`__ that runs as a web-service
+and allows sharing and discovering of new tracks.
+
+This documentation contains content pertaining to the installation, maintenance
+and administration of a Fietsboek setup. Documentation about using Fietsboek
+and extending/modifying Fietsboek will follow in the future.
+
+Fietsboek is `FLOSS
+<https://en.wikipedia.org/wiki/Free_and_open-source_software>`__, licensed
+under the `AGPLv3 license <https://www.gnu.org/licenses/agpl-3.0.en.html>`__.
+Fietsboek is built on top of the following open source technologies:
+
+* `Pyramid <https://trypyramid.com/>`__
+* `gpxpy <https://pypi.org/project/gpxpy/>`__
+* Jürgen Berkemeier's `GPXViewer <https://www.j-berkemeier.de/GPXViewer/>`__
+* `OpenStreetMap <https://www.openstreetmap.org/>`__
+* `Bootstrap <https://getbootstrap.com/>`__ and `Bootstrap Icons
+ <https://icons.getbootstrap.com/>`__
+* `OpenSans <https://github.com/googlefonts/opensans>`__ (Copyright 2020 The
+ Open Sans Project Authors)
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/make.bat b/doc/make.bat
new file mode 100644
index 0000000..32bb245
--- /dev/null
+++ b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd