diff --git a/DEVELOPMENT.rst b/DEVELOPMENT.rst index 5ae1ac040..38cb7a101 100644 --- a/DEVELOPMENT.rst +++ b/DEVELOPMENT.rst @@ -15,11 +15,14 @@ Installation and start of the development version a. Check requirements ''''''''''''''''''''' -Make sure that you have installed `Python (>= 3.4) -`_, `Node.js (>=0.10) `_ and -`Git `_ on your system. See also step 1. a. in the -installation section in the `README.rst -`_. +Make sure that you have installed `Python (>= 3.4) `_, +`Node.js (>=4.x) `_, `npm - Node Package Manager (>=3.x) +`_ and `Git `_ on your system. You also +need header files and a static library for Python. + +For Ubuntu 16.04 e. g. run:: + + $ sudo apt-get install git nodejs nodejs-legacy npm python3-dev b. Get OpenSlides source code @@ -44,7 +47,7 @@ d. Install dependencies Install all required Python packages:: - $ pip install -r requirements.txt + $ pip install --requirement requirements.txt Install all NPM and Bower packages and run several JavaScript build tasks:: @@ -65,15 +68,27 @@ Use the command-line interface:: See step 1. d. in the installation section in the `README.rst `_. -To get help on the command-line options run:: +To get help on the command line options run:: $ python manage.py --help -Later you might want to restart the server with the following command to -avoid opening new browser windows:: +Later you might want to restart the server with one of the following commands. + +To start OpenSlides with Daphne and one worker and to avoid opening new browser +windows run:: + + $ python manage.py start --no-browser + +To start OpenSlides with Daphne and four workers (avoid concurrent write +requests or use PostgreSQL, see below) run:: $ python manage.py runserver +To start OpenSlides with Geiss and one worker and to avoid opening new browser +windows (download Geiss and setup Redis before, see below) run:: + + $ python manage.py start --no-browser --use-geiss + Use gulp watch in a second command-line interface:: $ node_modules/.bin/gulp watch @@ -82,17 +97,19 @@ Use gulp watch in a second command-line interface:: 2. Installation on Windows -------------------------- -Follow the instructions above (Installation on GNU/Linux or Mac OS X) but -care of the following variations. +Follow the instructions above (Installation on GNU/Linux or Mac OS X) but care +of the following variations. -To get Python download and run the latest `Python 3.5 32-bit (x86) -executable installer `_. Note -that the 32-bit installer is required even on a 64-bit Windows system. If -you use the 64-bit installer, step d. of the instruction will fail unless -you installed the package Reportlab manually. +To get Python download and run the latest `Python 3.5 32-bit (x86) executable +installer `_. Note that the 32-bit +installer is required even on a 64-bit Windows system. If you use the 64-bit +installer, step d. of the instruction might fail unless you installed some +packages manually. -You have to install MS Visual C++ 2015 build tools before you install the -required python packages for OpenSlides (unfortunately Twisted 16.6.x needs it). +You have to install `MS Visual C++ 2015 build tools +`_ before you +install the required python packages for OpenSlides (unfortunately Twisted +16.6.x needs it). To setup and activate the virtual environment in step c. use:: @@ -104,35 +121,85 @@ All other commands are the same as for GNU/Linux and Mac OS X. 3. Running the test cases ------------------------- -a. Running Angular.js test cases -'''''''''''''''''''''''''''''''' +a. Running server tests +''''''''''''''''''''''' + +To run some server tests see `.travis.yml +`_. + + +b. Running AngularJS test cases +''''''''''''''''''''''''''''''' + +Run client tests by starting karma:: $ node_modules/.bin/karma start tests/karma/karma.conf.js -Installation OpenSlides in big mode -=================================== +OpenSlides in big mode +====================== -1. Install PostgreSQL und redis: +In the so called big mode you should use OpenSlides with Redis, PostgreSQL and a +webserver like Apache HTTP Server or nginx as proxy server in front of your +OpenSlides interface server. Optionally you can use `Geiss +`_ as interface server instead of Daphne. -apt-get install postgresql redis-server libpg-dev -TODO: Configure postgresql +1. Install and configure PostgreSQL and Redis +--------------------------------------------- -2. Install python dependencies +Install `PostgreSQL `_ and `Redis +`_. For Ubuntu 16.04 e. g. run:: -pip install django-redis asgi-redis django-redis-sessions psycopg2 + $ sudo apt-get install postgresql libpq-dev redis-server -3. Change settings.py +Be sure that database and redis server is running. For Ubuntu 16.04 e. g. this +was done automatically if you used the package manager. -(See comments in the settings) +Then add database user and database. For Ubuntu 16.04 e. g. run:: -The relevant settings are: DATABASES, CHANNEL_LAYERS, CACHES + $ sudo -u postgres createuser --pwprompt --createdb openslides + $ sudo -u postgres createdb --owner=openslides openslides -4. Start one or more workers: -python manage.py runworker +2. Install additional packages +------------------------------ -5. Start daphne. Set the DJANGO_SETTINGS_MODULE and the PYTHONPATH +Install some more required Python packages:: -DJANGO_SETTINGS_MODULE=settings PYTHONPATH=personal_data/var/ daphne openslides.asgi:channel_layer + $ pip install -r requirements_big_mode.txt + + +3. Change OpenSlides settings +----------------------------- + +Create OpenSlides settings file if it does not exist:: + + $ python manage.py createsettings + +Change OpenSlides settings file (usually called settings.py): Setup +`DATABASES` entry as mentioned in the settings file. Set `use_redis` to +`True`. + +Populate your new database:: + + $ python manage.py migrate + + +4. Run OpenSlides +----------------- + +First start e. g. four workers:: + + $ python manage.py runworker --threads 4 + +To start Daphne as protocol server run:: + + $ export DJANGO_SETTINGS_MODULE=settings + $ export PYTHONPATH=personal_data/var/ + $ daphne openslides.asgi:channel_layer + +To use Geiss instead of Daphne, just download Geiss and start it:: + + $ python manage.py getgeiss + $ ./personal_data/var/geiss diff --git a/README.rst b/README.rst index f3133ce22..ed622c773 100644 --- a/README.rst +++ b/README.rst @@ -40,14 +40,19 @@ You can setup a virtual Python environment using the virtual environment *Note: For Ubuntu 14.04 you have to install the pyvenv binary package* ``python3.4-venv`` *before.* -Create your OpenSlides directory, change to it, setup and activate the -virtual environment:: +*Note: For Ubuntu 16.04 you have to install the pyvenv binary package* +``python3-venv`` *before.* + +Create your OpenSlides directory and change to it:: $ mkdir OpenSlides $ cd OpenSlides + +Setup and activate the virtual environment:: + $ python3 -m venv .virtualenv $ source .virtualenv/bin/activate - $ pip install -U setuptools + $ pip install --upgrade setuptools pip c. Install OpenSlides @@ -75,7 +80,7 @@ To start OpenSlides simply run:: $ openslides If you run this command the first time, a new database and the admin account -(Username: `admin`, Password: `admin`) will be created. Please change the +(Username: ``admin``, Password: ``admin``) will be created. Please change the password after first login! OpenSlides will start a webserver. It will also try to open the webinterface in @@ -119,9 +124,9 @@ If you want to contribute to OpenSlides, have a look at `OpenSlides website Installation for big assemblies =============================== -The installation steps described above install OpenSlides in a way that does -NOT support hundreds of concurrent clients. To install OpenSlides for big -assemblies some config variables have to be changed in the OpenSlides settings +The installation steps described above install OpenSlides in a way that +does NOT support hundreds of concurrent clients. To install OpenSlides for +big assemblies some variables have to be changed in the OpenSlides settings file (usually called settings.py). The configuration values that have to be altered are: @@ -129,19 +134,23 @@ The configuration values that have to be altered are: * CACHES * CHANNEL_LAYERS * DATABASES +* SESSION_ENGINE -Please see: +You should use a webserver like Apache HTTP Server or nginx to serve the +static and media files as proxy server in front of your OpenSlides +interface server. You also should use a database like PostgreSQL and Redis +as channels backend, cache backend and session engine. Finally you should +start some WSGI workers and one or more interface servers (Daphne or Geiss). -* http://channels.readthedocs.io/en/latest/deploying.html +Please see the respective section in the `DEVELOPMENT.rst +`_ and: + +* https://channels.readthedocs.io/en/latest/deploying.html +* https://github.com/ostcar/geiss * https://docs.djangoproject.com/en/1.10/topics/cache/ * https://github.com/sebleier/django-redis-cache * https://docs.djangoproject.com/en/1.10/ref/settings/#databases -You should use a webserver like Apache HTTP Server or nginx to serve the static -and media files as proxy server in front of your OpenSlides server. You also -should use a database like PostgreSQL and Redis as channels backend and cache -backend. - Used software ============= diff --git a/requirements_big_mode.txt b/requirements_big_mode.txt new file mode 100644 index 000000000..908d91142 --- /dev/null +++ b/requirements_big_mode.txt @@ -0,0 +1,8 @@ +# Requirements for OpenSlides in production +-r requirements_production.txt + +# Requirements for Redis and PostgreSQL support +asgi-redis>=1.0.0,<1.1 +django-redis>=4.7.0,<4.8 +django-redis-sessions>=0.5.6,<0.6 +psycopg2>=2.6.2,<2.7 diff --git a/requirements_production.txt b/requirements_production.txt index 0436389e0..0a8f51e49 100644 --- a/requirements_production.txt +++ b/requirements_production.txt @@ -7,9 +7,3 @@ PyPDF2>=1.26,<1.27 roman>=2.0,<2.1 setuptools>=29.0,<35.0 bleach>=1.5.0,<1.6 - -# Requirements for Redis and PostgreSQL support -asgi-redis>=1.0.0,<1.1 -django-redis>=4.7.0,<4.8 -django-redis-sessions>=0.5.6,<0.6 -psycopg2>=2.6.2,<2.7