diff --git a/README.md b/README.md
index 95f293fe37b2e17496ce685a164742e359633226..a85bb32400c64028536e8adb3883a93ee64aadcf 100644
--- a/README.md
+++ b/README.md
@@ -89,3 +89,153 @@ Define in your host_vars/<host> the dictionary `webapps`
 
 - name: restart uwsgi instance <instance_name>
   service: name="uwsgi@<instance_name>" state=restarted
+
+## webserver
+
+This role manages the nginx configuration for a host based on the variable `webservers`.
+
+### Structure
+
+Every host (e.g. `web`) has a list of servers, corresponding to a configuration file which can be enabled or disabled.
+Each server has a list of sites, corresponding to a `server` block in the configuration file.
+Each site has a `type`, general information about the proxy and how to link it to the internal application, and depending on the site type a list of `locations`.
+
+Configuration files are generated in `/etc/nginx/(proxy-)?sites-available/` and - if enabled - linked in `/etc/nginx/(proxy-)?sites-enabled/`.
+Two nginx configuration files (`/etc/nginx/nginx.conf` and `/etc/nginx/nginx-proxy.conf`) are generated with their corresponding systemd units.
+
+If no servers are configured (i.e. the `webservers` variables missing), example config files are deployed and all files in the `-enabled` directories are included.
+If servers are configured, the generated configuration files end with `.conf` and only those are included.
+
+### Variables
+
+#### Server
+
+* `name`: an identifier, unique
+* `enabled`: `yes` or `no`
+* `servers`: list of `sites`
+
+#### Site
+
+* `type`: `webapp` or special, e.g. `mediawiki`, determines template in `webserver/templates/sites/`
+* one of (used for nginx-proxy-communication):
+  - `port`: ip port (e.g. 62000)
+  - `socket`: path to unix socket
+* one of:
+  - `server_name`: domain name of the website
+  - `server_names`: list of domain names of the website
+* `root`: path to website root directory
+* `indices`: list of index file names
+* `forward_http`: if `yes`, the proxy redirects HTTP requests to HTTPS (cf. `sites/httprewrite.conf`, optional)
+* `forward_ip`: if `yes`, the proxy redirects requests to the hosts IP to the hosts domain name (cf. `sites/iprewrite.conf`, optional)
+  - only useful on one server per host
+* `forward_hostnames`: one of (optional)
+  - list of hostnames to redirect to this servers domain
+  - dict:
+    - `path`: path under this domain to redirect the hostnames to
+    - `hostnames`: list of hostnames to redirect to this domain
+* `no_ssl`: if `yes`, the proxy listens to HTTP, not HTTPS
+* `certificate`: path to the TLS certificate file (required for HTTPS)
+* `private_key`: path to the TLS private key file (required for HTTPS)
+* `cipher_strength`: `modern` or `intermediate` (cf. `vars/main.yml`, optional)
+* `use_sso`: include single sign on for this server
+* `sso_protect_all`: if `no`, proxy locations do not automatically require single sign on auth if `use_sso` is set (default `yes`, optional)
+* `include_acme`: if `yes`, the acmetool snippet is included (optional)
+* `include_snippets`: list of snippets files (in `/etc/nginx/snippets/`) to include (optional)
+* `internal_locations`: list of internal locations
+  - *required* to generate internal config (empty list != omitted)
+  - used by site type `webapp`
+* `public_locations`:
+  - list of public locations
+  - required to generate proxy config
+
+#### Location
+
+* `type`: location block type (cf. `templates/locations/`)
+* `path`: which path this location maps to
+* `exact`: if `yes`, the path matches exactly, without matching subdirectories (cf. `location =`, optional)
+* `prefer_to_regex`: if `yes`, if this location is the longest prefix match, regexes are not matched (cf. `location ^~`, optional)
+* `regex`: if yes, the path specification is a regular expression (cf. `location ~`, optional)
+* `case_insensitive`: if `yes`, the path regex is case insensitive (cf. `location ~*`, optional)
+  - only with `regex: yes`
+* `locations`: list of locations, nested in this location (optional)
+* `root`: the root directory of this location (optional)
+* `indices`: the index pages of this location (optional)
+* `error_page`: the error page of this location (optional)
+* `params`: dictionary of parameters passed through to the nginx config (optional)
+* `conditions`: list of condition dictionaries passed for this location (optional)
+  - `condition`: the part inbetween `if` and `{`
+  - `actions`: list of lines inbetween `{` and `}`
+* `pam_auth`: if set, this location requires PAM authentication
+  - `name`: the name to show the user (default `FSMPI`, optional)
+  - `service`: the PAM service required (default `nginx`, optional)
+* `basic_auth`: if set, this location requires basic auth
+  - `name` the name to show to the user (default `FSMPI`, optional)
+  - `file`: the file to get users and passwords from
+* `allow_only_networks`: list of dictionaries this location is limited to (optional)
+  - `network`: IP/CIDR notation allowed to access this site
+  - `comment`: comment explaining this location (for config readability, required)
+
+##### fastcgi
+
+To be used with a fastcgi application, e.g. `php-fpm`.
+
+* `socket`: fastcgi socket (either host:port or unix:path)
+* `script_name`: `SCRIPT_FILENAME` without `$document_root` (optional)
+* `pass_real_ip`: if `yes`, `$http_x_real_ip` is passed as `REMOTE_ADDR` (optional)
+* `index`: filename appended to paths ending with `/` (optional)
+* `pass_user`: `$remote_user` is passed as `REMOTE_USER` (optional)
+
+##### proxy
+
+Passes this request to a HTTP(S) proxy, used e.g. in the nginx-proxy.
+
+* `sso_protect`: if `yes`, this location requires single sign on authentication
+  - by default `sso_protect_all` is `yes`, therefore this is only required if only some locations should be protected
+* ony of (optional):
+  - `proxy_host`: domain to pass the request to
+  - `proxy_port`: port (on localhost) to pass this request to
+  - `proxy_unix`: path to unix socket to pass this request to
+  - if none of these, `server.port` or `server.socket` is used
+* `proxy_relative`: if `yes`, the request path is passed to the proxy (default: `no`, optional), otherwise all requests are passed to `/`
+* `pass_ip`: if `yes`, host, remote address and protocol scheme are passed as headers (optional)
+* `proxy_headers`: list of headers to pass along the request (optional)
+  - `key`: header name
+  - `value`: header value
+
+##### uwsgi
+
+Passes requests to an uwsgi socket.
+
+* `socket`: unix (with `unix:` prefix) or ip socket uwsgi listens on
+* `pass_ip`: if `yes`, host and remote address are passed as headers (optional)
+* `pass_real_ip`: if `yes`, host and remote address from `real_ip` are passed (optional)
+
+##### static
+
+Server static files from a directory.
+
+* `alias`: filesstem directory equivalent to this location (optional)
+  - otherwise, `root` from the location of server is used
+
+##### redirect
+
+Redirects the request to another location.
+
+* `target`: URL (with or without host) to redirect to
+* `temporary`: if `yes`, a temporary redirect (302) is used, otherwise a permanent (301) (optional, default `no`)
+
+##### named
+
+Passes this request to a hidden `@location` if the file is not found.
+
+* `name`: the name of the named location to pass this request to (without `@`)
+
+##### param-only
+
+Sets parameters (c.f. `params` above) for this location, does nothing special.
+
+##### deny
+
+Disallows to see this page (cf. `deny all`).
+
+