Merge pull request #109 from open-zaak/feature/sphinx

Setting up technical documentation

.gitignore

@@ -15,6 +15,7 @@ __pycache__
 # Generated files
 src/openzaak/static/fonts
 src/openzaak/static/css/screen.css
+docs/_build
 
 # Coverage reports
 /reports/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Open zaak"
+copyright = "2019, Maykin Media"
+author = "Maykin Media"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.todo"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_logo = "logo.png"
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+todo_include_todos = True

docs/deployment/code/env

@@ -0,0 +1,11 @@
+DJANGO_SETTINGS_MODULE=openzaak.conf.production
+# generate one on https://www.miniwebtool.com/django-secret-key-generator/
+SECRET_KEY=replace-me-because-i-am-insecure
+ALLOWED_HOSTS=openzaak.gemeente.nl
+
+DB_HOST=localhost
+DB_NAME=production
+DB_USER=openzaak
+DB_PASSWORD=<database password>
+
+IS_HTTPS=yes

docs/deployment/code/nginx-vhost.conf

@@ -0,0 +1,108 @@
+# Backend server
+upstream production {
+    server 127.0.0.1:8000;
+}
+
+# Redirect HTTP traffic to HTTPS
+server {
+    listen 80;
+    server_name openzaak.gemeente.nl;
+    rewrite ^ https://openzaak.gemeente.nl$request_uri?;
+}
+
+# Listen for HTTPS traffic
+server {
+    server_tokens off;
+    listen 443 ssl;
+    server_name openzaak.gemeente.nl;
+    client_max_body_size 4G;
+
+    # Enable Gzip
+    gzip  on;
+    gzip_http_version 1.0;
+    gzip_comp_level 2;
+    gzip_min_length 1100;
+    gzip_buffers     4 8k;
+    gzip_proxied any;
+    gzip_types
+
+      # text/html is always compressed by HttpGzipModule
+      text/css
+      text/javascript
+      text/xml
+      text/plain
+      text/x-component
+      application/javascript
+      application/json
+      application/xml
+      application/rss+xml
+      font/truetype
+      font/opentype
+      application/vnd.ms-fontobject
+      image/svg+xml;
+
+    gzip_static on;
+
+    gzip_proxied        expired no-cache no-store private auth;
+    gzip_disable        "MSIE [1-6]\.";
+    gzip_vary           on;
+
+    ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # Disable SSLv3 for security reasons
+    ssl_session_timeout 1d;
+    ssl_session_cache shared:SSL:50m;
+
+    ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';
+    ssl_prefer_server_ciphers on;
+    ssl_dhparam /etc/ssl/certs/dhparam.pem;
+
+    # Uncomment after verifying that the SSL setup is working
+    # add_header Strict-Transport-Security max-age=15768000;
+    add_header X-XSS-Protection "1; mode=block";
+    add_header X-Content-Type-Options nosniff;
+
+    ssl on;
+    ssl_certificate /etc/ssl/sites/public.cert;
+    ssl_certificate_key /etc/ssl/sites/private.key;
+
+    access_log /srv/sites/production/log/nginx/access.log;
+    error_log /srv/sites/production/log/nginx/error.log info;
+
+    location /static/ {
+        expires 15m;
+        alias /srv/sites/production/static/;
+    }
+
+    location /media/ {
+        # expires 1d;
+        alias /srv/sites/production/media/;
+    }
+
+    location /private-media {
+        internal;
+        alias /private-media;
+    }
+
+    location / {
+        proxy_pass_header Server;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $server_name;
+        proxy_set_header X-Scheme $scheme;
+        proxy_connect_timeout 300s;
+        proxy_read_timeout 300s;
+
+        proxy_set_header Host $http_host;
+        proxy_redirect off;
+        proxy_pass_request_headers on;
+
+        proxy_pass http://production;
+    }
+
+    # Error pages
+    error_page 500 502 504 /500.html;
+    location = /500.html {
+        root /srv/sites/production/src/openzaak/templates/;
+    }
+
+}

docs/deployment/code/openzaak.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Open zaak production
+After=syslog.target
+
+[Service]
+ExecStart=/srv/sites/production/env/bin/uwsgi \
+    --http :8000 \
+    --module openzaak.wsgi \
+    --chdir /srv/sites/production/src \
+    --processes 2 \
+    --threads 2 \
+    --buffer-size 32768 \
+    --socket /var/run/openzaak/production.socket
+User=openzaak
+Group=openzaak
+Restart=on-failure
+KillSignal=SIGQUIT
+Type=notify
+StandardError=syslog
+NotifyAccess=all

docs/deployment/code/openzaak.socket

@@ -0,0 +1,11 @@
+[Unit]
+Description=Socket for Open zaak production
+
+[Socket]
+ListenStream=/var/run/openzaak/production.socket
+SocketUser=openzaak
+SocketGroup=openzaak
+SocketMode=0660
+
+[Install]
+WantedBy=sockets.target

docs/deployment/containers.rst

@@ -0,0 +1,3 @@
+==============================
+Deploying as Docker containers
+==============================