diff options
Diffstat (limited to 'doc/administration')
| -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 |
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. |