Add installation instructions

README.md

@@ -14,3 +14,47 @@ System zur Verwaltung von Protokollen und Sitzungen.
 * Rechteverwaltung (interne Abschnitte)
 * Hochladen der Tagesordnung in einen Kalender
 * externe Protokolle ohne Protokollsyntax
+
+# HowTo Setup
+
+Required infrastructure:
+
+* some WSGI-capable webserver (nginx + uwsgi, …)
+* some database (postgres, …)
+* some LDAP server (Samba 4, slapd, …) for accounts and groups
+* texlive
+* some message broker for [celery](http://docs.celeryproject.org/en/latest/getting-started/brokers/) (redis, …)
+
+Optional infrastructure:
+
+* a mail server (for sending protocols and invitations)
+* a CUPS printing server (for printing protocols and decisions)
+* an [Etherpad](https://github.com/ether/etherpad-lite) (for writing the protocol collectively)
+* a Mediawiki instance (for uploading the protocols there)
+* a CalDAV server (for uploading the events)
+
+Steps:
+
+1. clone the [repository](https://git.fsmpi.rwth-aachen.de/protokollsystem/proto3)
+2. create a python virtualenv and install the packages from `requirements.txt` there
+3. create a database (tested with postgres and sqlite, but feel free to use whatever you like and [SQLAlchemy](http://docs.sqlalchemy.org/en/latest/dialects/index.html) supports
+4. copy `config.py.example` to `config.py` and edit it
+  * **do** change everything commented with `change this`
+  * do **not** change the lines commented with `do not change`
+  * deactivate unwanted features with `SOMETHING_ACTIVE = False`
+  * if you want to use a feature, set the connection configuration lines accordingly
+  * define a list of authentication backends (usually one):
+    - use LdapManager for slapd
+    - use ADManager for Samba
+    - write your own for anything else (see `auth.py`, just the methods `authenticate` and `groups` are required)
+  * define the available printers (if wanted) with a list of options they should use (see lpoptions)
+  * if you do not know what a MediaWiki-domain is, you probably don't need it
+  * fix the path to the fonts (and select which to use)
+  * most points should be documented in the example config
+5. create the database schema with `./server.py db upgrade`
+6. configure your server to run the wsgi-application and the celery-server
+  * if you use systemd, example service files are located in `example-config/` in this repository
+7. configure your webserver to serve the wsgi-application
+  * if you use uwsgi+nginx, example config if located in `example-config/`
+  * don't forget to pass the correct IP if you use some proxy-setup and want to use IP-based access per protocol type
+8. Test if it is working properly

config.py.example

@@ -4,7 +4,7 @@ SQLALCHEMY_TRACK_MODIFICATIONS = False # do not change
 
 SECRET_KEY = "something random" # change this
 
-DEBUG = False
+DEBUG = False # do not change
 
 # mailserver (optional)
 MAIL_ACTIVE = True
@@ -13,10 +13,10 @@ MAIL_HOST = "mail.example.com:465"
 MAIL_USER = "user" # set to "" for unauthenticated sending
 MAIL_PASSWORD = "password" # set to "" for unauthenticated sending
 MAIL_USE_TLS = True # should match the port in MAIL_HOST (if present there)
-MAIL_USE_STARTTLS = False # Usually, it's either this or SMTPS
+MAIL_USE_STARTTLS = False # Usually, it's either this or SMTPS, not both
 
 # (local) message queue (necessary)
-CELERY_BROKER_URL = "redis://localhost:6379/0"
+CELERY_BROKER_URL = "redis://localhost:6379/0" # change this if you do not use redis or it is running somewhere else
 CELERY_TASK_SERIALIZER = "pickle" # do not change
 CELERY_ACCEPT_CONTENT = ["pickle"] # do not change
 
@@ -31,7 +31,7 @@ PRINTING_PRINTERS = [
 
 # etherpad (optional)
 ETHERPAD_ACTIVE = True
-ETHERPAD_URL = "https://example.com/etherpad"
+ETHERPAD_URL = "https://example.com/etherpad" # without /p/…
 EMPTY_ETHERPAD = """Welcome to Etherpad!
 
 This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!
@@ -52,7 +52,7 @@ WIKI_DOMAIN = "domain" # set to None if not necessary
 CALENDAR_ACTIVE = True
 CALENDAR_URL = "https://user:password@calendar.example.com/dav/"
 CALENDAR_DEFAULT_DURATION = 3 # default meeting length in hours
-CALENDAR_MAX_REQUESTS = 10
+CALENDAR_MAX_REQUESTS = 10 # number of retries before giving up (some caldav servers like to randomly reply with errors)
 
 SESSION_PROTECTION = "strong" # do not change
 
@@ -72,7 +72,7 @@ AUTH_BACKENDS = [
         ca_cert="/etc/ssl/certs/example-ca.pem")
 ]
 
-OBSOLETION_WARNING = """Please migrate your account!"""
+OBSOLETION_WARNING = """Please migrate your account!""" # not important
 
 # lines of error description
 ERROR_CONTEXT_LINES = 3
@@ -86,6 +86,7 @@ MAX_INDEX_DAYS = 14
 
 # mail to contact in case of complex errors
 ADMIN_MAIL = "admin@example.com"
+# users with this group may see and do everything
 ADMIN_GROUP = "admin"
 
 # accept protocols even with some errors
@@ -93,45 +94,55 @@ ADMIN_GROUP = "admin"
 # not recommended for regular operation
 PARSER_LAZY = False
 
-# minimum similarity (0-100) todos need to have to be considered equal
+# minimum similarity (0-100) todos need to have to be considered equal while importing
 FUZZY_MIN_SCORE = 90
 
 # choose something nice from fc-list
 # Nimbus Sans looks very much like Computer Modern
 FONTS = {
     "main": {
-        "regular": "Nimbus Sans",
-        "bold": "NimbusSans",
-        "italic": "NimbusSans",
-        "bolditalic": "NimbusSans"
+        "extension": ".otf",
+        "path": "/usr/share/fonts/OTF/",
+        "regular": "NimbusSans-Regular",
+        "bold": "NimbusSans-Bold",
+        "italic": "NimbusSans-Oblique",
+        "bolditalic": "NimbusSans-BoldOblique"
     },
     "roman": {
-        "regular": "Nimbus Roman",
-        "bold": "Nimbus Roman",
-        "italic": "Nimbus Roman",
-        "bolditalic": "Nimbus Roman"
+        "extension": ".otf",
+        "path": "/usr/share/fonts/OTF/",
+        "regular": "NimbusRoman-Regular",
+        "bold": "NimbusRoman-Bold",
+        "italic": "NimbusRoman-Italic",
+        "bolditalic": "NimbusRoman-BoldItalic"
     },
     "sans": {
-        "regular": "Nimbus Sans",
-        "bold": "NimbusSans",
-        "italic": "NimbusSans",
-        "bolditalic": "NimbusSans"
+        "extension": ".otf",
+        "path": "/usr/share/fonts/OTF/",
+        "regular": "NimbusSans-Regular",
+        "bold": "NimbusSans-Bold",
+        "italic": "NimbusSans-Oblique",
+        "bolditalic": "NimbusSans-BoldOblique"
     },
     "mono": {
-        "regular": "Nimbus Mono PS",
-        "bold": "Nimbus Mono PS",
-        "italic": "Nimbus Mono PS",
-        "bolditalic": "Nimbus Mono PS"
+        "extension": ".otf",
+        "path": "/usr/share/fonts/OTF/",
+        "regular": "NimbusMonoPS-Regular",
+        "bold": "NimbusMonoPS-Bold",
+        "italic": "NimbusMonoPS-Italic",
+        "bolditalic": "NimbusMonoPS-BoldItalic"
     }
 }
 
-# local filesystem path to save documents
+# local filesystem path to save compiled and uploaded protocols (and attachments)
 DOCUMENTS_PATH = "documents"
 
 # keywords indicating private protocol parts
 PRIVATE_KEYWORDS = ["private", "internal", "privat", "intern"]
 
 # list of bulletpoints to use in latex
+# these are latex-defaults, add more if you like more
+# they are cycled as often as necessary to allow (theoretically) infinite nesting depth
 LATEX_BULLETPOINTS = [
     r"\textbullet",
     r"\normalfont \bfseries \textendash",
@@ -157,6 +168,8 @@ HTML_LEVEL_OFFSET = 3
 def dummy_todomail_provider():
     return {"example": ("Name", "mail@example.com")}
 
+# if you want to generate this mapping automatically
+# manually creating todomails through the web interface will still be possible for every authenticated user
 # list of functions that return dicts mapping todomail-keys to a tuple containing name and mail address
 ADDITIONAL_TODOMAIL_PROVIDERS = [
     dummy_todomail_provider

example-config/celery.service

+[Unit]
+Description=Protokollsystem-Celery
+After=network.target
+
+[Service]
+User=protokolle
+Group=protokolle
+WorkingDirectory=/var/www/protokollsystem
+Environment=VIRTUAL_ENV="/var/www/protokollsystem"
+ExecStart=/var/www/protokollsystem/program/bin/celery -A server.celery worker --loglevel=DEBUG --concurrency=4
+Restart=always
+
+[Install]
+WantedBy=multi-user.target

example-config/protokollsystem

+server {
+	listen 62000;
+	server_name protokolle.example.com;
+	root /var/www/protokolle;
+	index index.html index.py;
+
+	location / {
+		include uwsgi_params;
+		client_max_body_size 5M;
+		proxy_set_header        X-Real-IP       $realip_remote_addr;
+		proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
+		uwsgi_param  REMOTE_ADDR        $realip_remote_addr;
+		uwsgi_pass unix:///run/uwsgi/app/protokollsystem.sock;
+	}
+	location /static {
+		alias /var/www/protokolle/static;
+		try_files $uri $uri/ =404;
+	}
+}
+

example-config/protokollsystem.service

+[Unit]
+Description=Protokollsystem
+After=network.target
+Wants=protokollsystem-celery.service
+
+[Service]
+Environment=LDAPTLS_CACERT=/etc/ssl/certs/ldap_chain.pem
+ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/apps-available/protokollsystem.ini
+Restart=always
+KillSignal=SIGTERM
+Type=notify
+NotifyAccess=all
+
+[Install]
+WantedBy=multi-user.target

example-config/uwsgi.ini

+[uwsgi]
+uwsgi-socket = /run/uwsgi/app/protokollsystem/protokollsystem.sock
+#http = localhost:5000
+chmod-socket = 660
+chown-socket = protokolle:www-data
+autoload =
+master =
+processes = 4
+workers = 4
+prio = -5
+harakiri = 5
+buffer-size=32768
+mule = 
+#umask = 227
+chdir = /var/www/protokollsystem
+uid = protokolle
+gid = protokolle
+logto = /var/log/uwsgi/protokollsystem.log
+logfile-chown = protokolle:protokolle
+logfile-chmod = 664
+log-date =
+log-4xx = 
+log-5xx = 
+log-x-forwarded-for =
+plugin = python35
+virtualenv = /var/www/protokollsystem
+wsgi-file = /var/www/protokollsystem/server.py
+callable = app
+pyargv = server.py runserver
+manage-script-name =
+mount=/=/var/www/protokollsystem/server.py