Merge pull request #5814 from FinnStutzenstein/docs

Docs and security email

ADVANCED.rst

@@ -0,0 +1,64 @@
+Advanced configuration
+======================
+
+Docker Swarm Mode
+-----------------
+
+OpenSlides may also be deployed in Swarm mode.  Distributing instances over
+multiple nodes may increase performance and offer failure resistance.
+
+An example configuration file, ``docker-stack.yml.m4``, is provided.  Unlike
+the Docker Compose setup, this configuration will most likely need to be
+customized, especially its placement constraints and database-related
+preferences.
+
+Before deploying an instance on Swarm, please see `Database Configuration`_ and
+`Backups`_, and review your ``docker-stack.yml``
+
+
+Database Configuration
+----------------------
+
+It is fairly easy to get an OpenSlides instance up an running; however, for
+production setups it is strongly advised to review the database configuration.
+
+By default, the primary database cluster will archive all WAL files in its
+volume.  Regularly pruning old data is left up to the host system, i.e., you.
+Alternatively, you may disable WAL archiving by setting
+``PGNODE_WAL_ARCHIVING=off`` in ``.env`` before starting the instance.
+
+The provided ``docker-stack.yml.m4`` file includes additional database
+services which can act as hot standby clusters with automatic failover
+functionality.  To take advantage of this setup, the database services need to
+be configured with proper placement constraints.  Before relying on this setup,
+please familiarize yourself with `repmgr <https://repmgr.org/>`_.
+
+
+Backups
+-------
+
+All important data is stored in the database.  Additionally, the project
+directory should be included in backups to ensure a smooth recovery.
+
+The primary database usually runs in the ``pgnode1`` service (but see `Database
+Configuration`_ above).
+
+In some cases, it may be sufficient to generate SQL dumps with ``pg_dump``
+through ``docker exec`` to create backups.  However, for proper incremental
+backups, the host system can backup the cluster's data directory and WAL
+archives.
+
+The cluster's data directory is available as a volume on the host system.
+Additionally, the database archives its WAL files in the same volume by
+default.  This way, the host system can include the database volume in its
+regular filesystem-based backup routine and create efficient database backups
+suitable for point-in-time recovery.
+
+The `former management repository
+<https://github.com/OpenSlides/openslides-docker-compose/>`_ provides the
+script `openslides-pg-mgr.sh` which can enable Postgres' backup mode in all
+OpenSlides database containers.
+
+In Swarm mode, the primary database cluster may get placed on a number of
+nodes.  It is, therefore, crucial to restrict the placement of database
+services to nodes on which appropriate backups have been configured.

DEVELOPMENT.rst

@@ -10,9 +10,10 @@ Check requirements
 - ``git``
 - ``make``
 
-Note about migrating from previous OpenSlides3 development
+**Note about migrating from development
-setups: You must set the ``OPENSLIDES_USER_DATA_DIR`` variable in
+setups before version 3.4**: You must set the ``OPENSLIDES_USER_DATA_DIR`` variable in
-your ``server/personal_data/var/settings.py`` to  ``'/app/personal_data/var'``
+your ``server/personal_data/var/settings.py`` to  ``'/app/personal_data/var'``. Another
+way is to just delete this file. It is recreated with the right paths afterwards.
 
 
 Get OpenSlides source code
@@ -21,31 +22,35 @@ Get OpenSlides source code
 Clone current master version from `OpenSlides GitHub repository
 <https://github.com/OpenSlides/OpenSlides/>`_::
 
-    git clone https://github.com/OpenSlides/OpenSlides.git
+    git clone https://github.com/OpenSlides/OpenSlides.git --recurse-submodules
     cd OpenSlides
 
-TODO: submodules.
+When updating the repository, submodules must be updated explicitly, too::
+
+    git submodule update
 
 Start the development setup
 ''''''''''''''''''''''''''''''
+Use `make` to start the setup::
 
     make run-dev
 
+All your data (database, config, mediafiles) is stored in ``server/personal_data/var``.
+To stop the setup press Ctrl+C. To clean up the docker containers run::
 
-All you data (database, config, mediafiles) is stored in ``server/personal_data/var``.
+    make stop-dev
 
 Running the test cases
--------------------------
+'''''''''''''''''''''''
-
 For all services in submodules check out the documentation there.
 
-Server tests andscripts
+Server tests and scripts
-'''''''''''''''''''''''
+-------------------------
 You need to have python (>=3.8) and python-venv installed. Change your workdirectory to the server::
 
     cd server
 
-Setup an python virtual environment. If you have already done it, you can skip this step:
+Setup an python virtual environment. If you have already done it, you can skip this step::
 
     python3 -m venv .venv
     source .venv/bin/activate
@@ -55,7 +60,7 @@ Make sure you are using the correct python version (e.g. try with explicit minor
 
     source .venv/bin/activate
 
-To deactivate it type ``deactivate``. Running all tests and linters:
+To deactivate it type ``deactivate``. Running all tests and linters::
 
     black openslides/ tests/
     flake8 openslides/ tests/
@@ -64,7 +69,7 @@ To deactivate it type ``deactivate``. Running all tests and linters:
     pytest tests/
 
 Client tests
-''''''''''''
+-------------
 You need `node` and `npm` installed. Change to the client's directory. For the first time, install all dependencies::
 
     cd client/

README.rst

@@ -5,44 +5,47 @@
 What is OpenSlides?
 ===================
 
-OpenSlides is a free, Web-based presentation and assembly system for
+OpenSlides is a free, web-based presentation and assembly system for
 managing and projecting agenda, motions, and elections of assemblies. See
 https://openslides.com for more information.
 
 Installation
 ============
 
-The main deployment method is using Docker and docker-compose. You only need to
+The main deployment method is using Docker and Docker Compose. You only need to
 have these tools installed and no further dependencies. If you want a simpler
 setup or are interested in developing, please refer to `development
 instructions
-<https://github.com/OpenSlides/OpenSlides/blob/master/DEVELOPMENT.rst>`_.
+<DEVELOPMENT.rst>`_.
-
-Note: This is temporary and will be replaced with nice scripts...
 
 First, you have to clone this repository::
 
-    $ git clone https://github.com/OpenSlides/OpenSlides.git
+    git clone https://github.com/OpenSlides/OpenSlides.git --recurse-submodules
-    $ cd OpenSlides/docker/
+    cd OpenSlides/docker/
 
-TODO: submodules.
+**Note about migrating from version 3.3 or earlier**: With OpenSlides 3.4 submodules
+and a Docker setup were introduced. If you ran into problems try to delete your
+``settings.py``. If you have an old checkout you need to check out the current master
+first and initialize all submodules::
+
+    git submodule update --init
 
 You need to build the Docker images for the client and server with this
 script::
 
-    $ ./build.sh all
+    ./build.sh all
 
 You must define a Django secret key in ``secrets/django.env``, for example::
 
-    $ printf "DJANGO_SECRET_KEY='%s'\n" \
+    printf "DJANGO_SECRET_KEY='%s'\n" \
       "$(tr -dc 'a-zA-Z0-9' < /dev/urandom | head -c 64)" > secrets/django.env
 
 We also strongly recommend that you set a secure admin password but it is not
 strictly required.  If you do not set an admin password, the default login
 credentials will be displayed on the login page.  Setting the admin password::
 
-    $ cp secrets/adminsecret.env.example secrets/adminsecret.env
+    cp secrets/adminsecret.env.example secrets/adminsecret.env
-    $ vi secrets/adminsecret.env
+    vi secrets/adminsecret.env
 
 Afterwards, generate the configuration file::
 
@@ -50,12 +53,12 @@ Afterwards, generate the configuration file::
 
 Finally, you can start the instance using ``docker-compose``::
 
-    $ docker-compose up
+    docker-compose up
-    $ # or:
+    # or:
-    $ docker-compose up -d
+    docker-compose up -d
-    $ docker-compose logs
+    docker-compose logs
-    $ # ...
+    # ...
-    $ docker-compose down
+    docker-compose down
 
 More settings
 -------------
@@ -63,74 +66,13 @@ More settings
 When generating the ``docker-compose.yml``, more settings can be adjusted in the
 ``docker/.env`` file. All changes for the backend are passed into djangos ``settings.py``.
 You can find more information about most settings `here
-<https://github.com/OpenSlides/OpenSlides/blob/master/server/SETTINGS.rst>`_. To generate
+<server/SETTINGS.rst>`_. To generate
 the ``docker-compose.yml`` use this command::
 
-    $ ( set -a; source .env; m4 docker-stack.yml.m4 ) > docker-stack.yml
+    ( set -a; source .env; m4 docker-stack.yml.m4 ) > docker-stack.yml
-
-
-Docker Swarm Mode
------------------
-
-OpenSlides may also be deployed in Swarm mode.  Distributing instances over
-multiple nodes may increase performance and offer failure resistance.
-
-An example configuration file, ``docker-stack.yml.m4``, is provided.  Unlike
-the Docker Compose setup, this configuration will most likely need to be
-customized, especially its placement constraints and database-related
-preferences.
-
-Before deploying an instance on Swarm, please see `Database Configuration`_ and
-`Backups`_, and review your ``docker-stack.yml``
-
-
-Database Configuration
-----------------------
-
-It is fairly easy to get an OpenSlides instance up an running; however, for
-production setups it is strongly advised to review the database configuration.
-
-By default, the primary database cluster will archive all WAL files in its
-volume.  Regularly pruning old data is left up to the host system, i.e., you.
-Alternatively, you may disable WAL archiving by setting
-``PGNODE_WAL_ARCHIVING=off`` in ``.env`` before starting the instance.
-
-The provided ``docker-stack.yml.m4`` file includes additional database
-services which can act as hot standby clusters with automatic failover
-functionality.  To take advantage of this setup, the database services need to
-be configured with proper placement constraints.  Before relying on this setup,
-please familiarize yourself with `repmgr <https://repmgr.org/>`_.
-
-
-Backups
--------
-
-All important data is stored in the database.  Additionally, the project
-directory should be included in backups to ensure a smooth recovery.
-
-The primary database usually runs in the ``pgnode1`` service (but see `Database
-Configuration`_ above).
-.
-In some cases, it may be sufficient to generate SQL dumps with ``pg_dump``
-through ``docker exec`` to create backups.  However, for proper incremental
-backups, the host system can backup the cluster's data directory and WAL
-archives.
-
-The cluster's data directory is available as a volume on the host system.
-Additionally, the database archives its WAL files in the same volume by
-default.  This way, the host system can include the database volume in its
-regular filesystem-based backup routine and create efficient database backups
-suitable for point-in-time recovery.
-
-The `former management repository
-<https://github.com/OpenSlides/openslides-docker-compose/>`_ provides the
-script `openslides-pg-mgr.sh` which can enable Postgres' backup mode in all
-OpenSlides database containers.
-
-In Swarm mode, the primary database cluster may get placed on a number of
-nodes.  It is, therefore, crucial to restrict the placement of database
-services to nodes on which appropriate backups have been configured.
 
+For an advanced database setup refer to the `advanced configuration 
+<ADVANCED.rst>`_.
 
 Bugs, features and development
 ================================
@@ -138,7 +80,10 @@ Bugs, features and development
 Feel free to open issues here on GitHub! Please use the right templates for
 bugs and features, and use them correctly. Pull requests are also welcome; for
 a general overview of the development setup refer the `development instructions
-<https://github.com/OpenSlides/OpenSlides/blob/master/DEVELOPMENT.rst>`_.
+<DEVELOPMENT.rst>`_.
+
+For security relevant issues **do not** create public issues and refer to
+our `security policy <SECURITY.md>`_.
 
 Used software
 =============

SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+Currently the recent versions (a year old at max) of the current major
+release are supported to get security fixes. For older versions we urge
+you to update to the most recent version of OpenSlides.
+
+## Reporting a Vulnerability
+
+Please let us know about the vulnerability by an email to
+[security@openslides.com](mailto:security@openslides.com). Do not create
+public issues for such issues. We will get in touch with you after reporting
+the issue.