OpenSlides/README.rst

160 lines
5.7 KiB
ReStructuredText
Raw Normal View History

============
OpenSlides
============
What is OpenSlides?
===================
2021-01-15 08:05:49 +01:00
OpenSlides is a free, web-based presentation and assembly system for
2020-08-14 15:21:35 +02:00
managing and projecting agenda, motions, and elections of assemblies. See
https://openslides.com for more information.
2021-02-05 09:55:54 +01:00
Installation
============
2021-02-05 09:55:54 +01:00
The main deployment method is using Git, Docker and Docker Compose. You only need
2022-02-16 12:52:12 +01:00
to have these tools installed and no further dependencies (m4 may not come preinstalled on your system). If you want a simpler
2020-08-14 15:21:35 +02:00
setup or are interested in developing, please refer to `development
2021-02-05 09:55:54 +01:00
instructions <DEVELOPMENT.rst>`_.
Get OpenSlides
--------------
First, you have to clone this repository to the latest stable branch::
git clone -b stable/3.4.x --single-branch https://github.com/OpenSlides/OpenSlides.git --recurse-submodules
2021-01-15 08:05:49 +01:00
**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::
2021-01-15 08:05:49 +01:00
git submodule update --init
Setup Docker Compose
--------------------
2021-02-05 09:55:54 +01:00
2021-02-15 11:19:05 +01:00
You need to build the Docker images and have to setup some configuration. First,
configure HTTPS by checking the `Using HTTPS`_ section. In this section are
reasons why HTTPS is required for large deployments.
2021-02-05 09:55:54 +01:00
2021-02-15 11:19:05 +01:00
Go to ``docker`` subdirectory::
2021-02-05 09:55:54 +01:00
cd docker
Then build all images with this script::
2021-01-15 08:05:49 +01:00
./build.sh all
2020-08-14 15:21:31 +02:00
You must define a Django secret key in ``secrets/django.env``, for example::
2021-01-15 08:05:49 +01:00
printf "DJANGO_SECRET_KEY='%s'\n" \
2020-08-14 15:21:31 +02:00
"$(tr -dc 'a-zA-Z0-9' < /dev/urandom | head -c 64)" > secrets/django.env
2020-08-14 15:21:35 +02:00
We also strongly recommend that you set a secure admin password but it is not
2021-02-05 09:55:54 +01:00
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::
2021-01-15 08:05:49 +01:00
cp secrets/adminsecret.env.example secrets/adminsecret.env
vi secrets/adminsecret.env
2020-08-14 15:21:35 +02:00
Afterwards, generate the configuration file::
2021-02-05 09:55:54 +01:00
m4 docker-compose.yml.m4 > docker-compose.yml
2020-08-14 15:21:35 +02:00
You can configure OpenSlides using the `.env` file. See `More settings`_. Another
hint: If you choose to deploy the default configuration, a https certificate is
needed, so make sure you have set it up beforehand.
Finally, you can start the instance using ``docker-compose``::
2021-01-15 08:05:49 +01:00
docker-compose up
2021-02-05 09:55:54 +01:00
OpenSlides is accessible on https://localhost/ (or https, if configured).
2021-02-05 09:55:54 +01:00
2022-02-16 12:52:12 +01:00
You can also use daemonized instance::
2021-02-05 09:55:54 +01:00
2021-01-15 08:05:49 +01:00
docker-compose up -d
docker-compose logs
docker-compose down
2021-02-15 11:19:05 +01:00
Using HTTPS
-----------
The main reason (next to obviously security ones) HTTPS is required originates
from the need of HTTP/2. OpenSlides uses streaming responses to asynchronously
send data to the client. With HTTP/1.1 one TCP-Connection per request is opened.
Browsers limit the amount of concurrent connections
2021-02-19 12:51:03 +01:00
(`reference <https://docs.pushtechnology.com/cloud/latest/manual/html/designguide/solution/support/connection_limitations.html>`_),
2021-02-15 11:19:05 +01:00
so you are limited in opening tabs. HTTPS/2 just uses one connection per browser
and eliminates these restrictions. The main point to use HTTPS is that browsers
only use HTTP/2 if HTTPS is enabled.
Setting up HTTPS
""""""""""""""""
Use common providers for retrieving a certificate and private key for your
deployment. Place the certificate and private key in ``caddy/certs/cert.pem``
and ``caddy/certs/key.pem``. To use a self-signed localhost certificate, you can
execute ``caddy/make-localhost-cert.sh``.
The certificate and key are put into the docker image into ``/certs/``, so
setting up these files needs to be done before calling ``./build.sh``. When you
update the files, you must run ``./build.sh proxy`` again. If you want to have a
more flexible setup without the files in the image, you can also mount the
folder or the certificate and key into the running containers if you wish to do
so.
If both files are not present, OpenSlides will be configured to run with HTTP
only. When mounting the files make sure, that they are present during the
container startup.
Caddy, the proxy used, wants the user to persist the ``/data`` directory. If you
are going to use HTTPS add a volume in your ``docker-compose.yml`` /
``docker-stack.yml`` persisting the ``/data`` directory.
2021-02-05 09:55:54 +01:00
2020-10-28 08:34:43 +01:00
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``.
2021-02-05 09:55:54 +01:00
You can find more information about most settings in the `settings documentation
<server/SETTINGS.rst>`_. To generate the ``docker-compose.yml`` use this command::
2020-10-28 08:34:43 +01:00
2021-02-05 09:55:54 +01:00
cd docker
( set -a; source .env; m4 docker-compose.yml.m4 ) > docker-compose.yml
2021-01-15 08:05:49 +01:00
For an advanced database setup refer to the `advanced configuration
<ADVANCED.rst>`_.
2021-02-05 09:55:54 +01:00
Bugs, features and development
================================
2020-08-14 15:21:35 +02:00
Feel free to open issues here on GitHub! Please use the right templates for
2021-02-05 09:55:54 +01:00
bugs and features, and use them correctly. Pull requests are also welcome. For
2020-08-14 15:21:35 +02:00
a general overview of the development setup refer the `development instructions
2021-01-15 08:05:49 +01:00
<DEVELOPMENT.rst>`_.
For security relevant issues **do not** create public issues and refer to
our `security policy <SECURITY.md>`_.
2021-02-05 09:55:54 +01:00
Used software
=============
OpenSlides uses the following projects or parts of them:
* several Python packages (see ``server/requirements/production.txt``)
2016-12-16 22:11:51 +01:00
2020-08-14 15:21:35 +02:00
* several JavaScript packages (see ``client/package.json``)
2021-02-05 09:55:54 +01:00
License and authors
===================
OpenSlides is Free/Libre Open Source Software (FLOSS), and distributed
2021-02-19 12:51:03 +01:00
under the MIT License, see `LICENSE file <LICENSE>`_. The authors of OpenSlides are
mentioned in the `AUTHORS file <AUTHORS>`_.