diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..bb593ee30f6781ef722a0586f8feaea83ec7d7fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,157 @@
+Description
+===========
+
+This role provides base methods for each system role.
+
+Requirement
+===========
+
+function defined variables
+--------------------------
+
+- function_packages (for container creation)
+
+User defined variables
+----------------------
+
+- users
+- usergroups
+- network.hostname
+- timezone
+
+Variables
+---------
+
+- system_home_mirror:
+  - description:
+    - URL of the producer's package repository
+  - hint: This variable is set by each system.
+
+- system_local_mirror:
+  - description:
+    - URL of the local package repository
+
+- system_mirror_directory:
+  - description:
+    - path to the root mirror directory on system for all system
+  - hint: This variable is set by function role.
+
+- system_supported_architures:
+  - description:
+    - list of system architectures supported by the system role; needed for installer und mirror
+  - hint: This variable is set by each system.
+
+- system_supported_releases:
+  - description:
+    - list of system releases supported by the system role; needed for installer und mirror
+  - hint: This variable is set by each system.
+
+- system_container_base_config:
+  - description:
+    - path to the base configuration file for containers
+  - hint: default file is provided by this system role
+
+- system_container_root: 
+  - description:
+    - path to the root directory for each jail 
+  - hint: default file is provided by this system role
+
+- system_suppress_container_creation:
+  - description:
+    - If this option is set to true, the system will be prepared for container usage, but none will be installed.
+  - choises: [true, false]
+  - default: false
+
+- system_installer_path:
+  - description:
+    - destination path to the directory for the installer
+
+- system_answer_path:
+  - description:
+    - destination path to the directory for the answer file
+
+- system_name:
+  - description:
+    - contains the distribution name of a system; needed for gatherpackages
+
+- system_gathered_packages:
+  - description:
+    - list of all packages; result of gatherpackages 
+
+- system_upgrade_states:
+  - description:
+    - a dictionary with the results of upgrade (see features)
+
+Tasks
+=====
+
+main
+----
+1. execute system configuration (see configure)
+
+configure
+---------
+
+1. set hostname 
+2. remove obsolete groups
+2. remove obsolete users
+2. add groups
+3. add users  
+4. append groups to users, if defined
+5. set timezone
+
+upgrade
+-------
+
+1. NOP
+
+createcontainer
+---------------
+
+1. NOP
+
+registercontainer
+-----------------
+
+1. NOP
+
+mirror
+------
+
+1. NOP
+
+installer
+---------
+
+1. NOP
+
+answerfile
+----------
+
+1. NOP
+
+gatherpackages
+--------------
+
+1. iterate over all roles and execute _loadpkgvars
+
+_loadpkgvars
+------------
+
+1. load default/main.yml of every role
+2. add content of package_packages to system_gathered_packages
+
+Features
+========
+
+The task upgrade have to generate a dictionary with the states of upgrade process. The dictionary has following structure:
+
+<inventory\_hostname>:
+    host: True|False
+    <name of container 1>: True|False
+    ...
+    <name container n>: True|False
+
+The key `host` contains the upgrade state of the inventory host. 
+The state `True` means that the host or container was upgraded. `False` that there are no upgrades for them. 
+