diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..77a7032dedd7f84671f2192bb5e61e1f4af96d43
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+# Webservices 
+
+
+## Roles
+
+- `acmetool`, manages let's encrypt certificates via acmetool
+- `debian-repository`, installs the software reprepro (very basic)
+- `lehrpreis`, teaching award nomination web app
+- `meckerkasten`, mimimi web app
+- `mediawiki`, setups mediawiki with php-fpm
+- `php-fpm`, setups php-fpm pools
+- `protokollsystem`, protocols, meetings, and everything management web app (TM)
+- `schildergenerator`, sign generator web app
+- `sentry`, error collection api and web app
+- `sso`, single signon web app 
+- `uwsgi-php`, deprecated
+- `uwsgi-python`, unified web app deployment role for python-based web apps 
+- `wahlhelfer`, setups wahlhelfer registration and scheduling web app
+- `wahlsystem`, setups an election management system
+- `webserver`,  configures nginx 
+- `wordpress`, setups wordpresses via an overlayfs technology 
+
+*Note:* Some roles are still undocumented.
+
+## uwsgi-python
+
+The idea of the role is to have only one role for all the python-based web apps. Instead of a role (and group) for every single app. 
+We distinguish between apps and instances. An app is the actual program, which can be instaciated more than once, which we call the instance.
+
+The role iterates over the list `webapps` (in the host vars) and import app and instance specific variable files.
+An app specific task snippet is imported if it configured in the variable files (see below). 
+
+We place the instance specific variable file under <inventory_dir>/vars/<instance>.yml. The app specific variable file is <role_dir>/vars/<app>.yml. 
+In the latter file there should be sensible defaults for _every_ variable used within the role. 
+
+This role needs the patch from this [pull-request](https://github.com/ansible/ansible/pull/39762) or ansible 2.6 or later.
+
+### Variables
+
+
+
+### How to create a new app
+
+### How to create a new app's instance