diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 50 | ||||
| -rw-r--r-- | doc/Makefile | 20 | ||||
| -rw-r--r-- | doc/administration/backup.rst | 61 | ||||
| -rw-r--r-- | doc/administration/configuration.rst | 66 | ||||
| -rw-r--r-- | doc/administration/installation.rst | 109 | ||||
| -rw-r--r-- | doc/administration/upgrading.rst | 67 | ||||
| -rw-r--r-- | doc/conf.py | 60 | ||||
| -rw-r--r-- | doc/index.rst | 46 | ||||
| -rw-r--r-- | doc/make.bat | 35 |
10 files changed, 468 insertions, 47 deletions
@@ -6,6 +6,7 @@ .coverage coverage.xml build/ +_build/ dist/ .tox/ nosetests.xml @@ -13,53 +13,9 @@ features are still lacking. Installation ------------ -- Generate a fresh virtual environment (recommended): - - virtualenv .venv - -- Install `fietsboek`: - - .venv/bin/pip install . - -- (Optionally: Install `lxml` to speed up GPX parsing) - - .venv/bin/pip install lxml - -- Adjust `production.ini` to your needs, mainly check the following settings: - - sqlalchemy.url - see https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls - session_key - set this to a random secret which is used to sign session keys - available_locales - set this to the list of locales you want to support - (by default, English and German translations are shipped) - enable_account_registration - whether users should be able to create new accounts - (set this to false for a private instance) - pyramid.default_locale_name - set the default language - email.from - the address that Fietsboek email's will be sent from - email.smtp_url - the URL of the SMTP server to send emails - (smtp://host:port, smtp+ssl://host:port, smtp+starttls://host:port) - email.smtp_user, email.smtp_password - SMTP login information - -- Create the database tables: - - .venv/bin/alembic -c production.ini upgrade head - -- Create the admin user - - .venv/bin/fietsctl -c production.ini useradd --admin - -- Start Fietsboek: - - .venv/bin/pserve production.ini - -This runs Fietsboek using Pyramid's [Waitress](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html) -server. If you need a better performance, read [the corresponding -section](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html) -in the Pyramid documentation and set up Fietsboek using an alternative server, -such as `gunicorn` or `mod_wsgi`. - -Note that it is advised to use a reverse proxy in front of Fietsboek to handle -SSL. **Not setting up a SSL capable reverse proxy puts the security of your -users at risk!** +Setup instructions are in the documentation. You can either build it locally +using [Sphinx](https://www.sphinx-doc.org/), or view the generated version +online: https://kingdread.de/fietsboek/ Development ----------- 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
|