diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f89abcd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# Edition Open Access 1.5
+
+Source code for the Edition Open Access website.
+Publications are provided in a number of different formats:
+
+- online HTML version
+- PDF
+- Ebook (EPUB)
+
+# Installation
+
+In order to provide a consistent environment we are using docker.
+A set of python scripts is used for automatisation.
+Installing and running the project work without Docker or the scripts is possible, but not recommended. In this case you are on your own.
+A bunch of other repositories are needed in order to run this project.
+They are automatically pulled by the init script.
+
+## Configuration
+
+- Environment variables: see file `.env`
+
+	These variables are available inside the `docker-compose.yaml` file and are also loaded into the python scripts.
+	The file is created/overwritten with default settings by the `init.py` script.
+
+- Django settings: see `src/eoa/settings.py`
+
+	For further information please check the django documentation.
+
+## Prerequisites
+
+- Python 3
+- Docker, Docker Compose
+
+## Initialise the Repository
+
+	$ ./scripts/init.py [--build]
+
+This will pull remote repositories and resources, initialize the database, etc.
+Force recreating the docker image by adding `--build` e.g. if `Dockerfile` or `requirements.txt` has changed.
+
+## Import Publications, Initialize CMS pages (TODO)
+
+Not yet documented.
+
+## Run the Webserver
+
+	$ ./scripts/run.py
+
+The webpage can now be explored in your local browser.
+
+## Stop the Webserver
+
+	$ ./scripts/stop.py
+
+## Run Command in the Webserver container
+
+	$ ./scripts/exec_in_container.py [-- CMD ...]
+
+## Clean the Repository
+
+	$ ./scripts/exit.py
+
+This should remove all remote repositories and resources not part of this repository.
+Docker images are not deleted though.
+
+# Installation for Production (TODO)
+
+Not documented yet.
+It might be necessary to tweak the django settings, among other adjustments.
diff --git a/scripts/init.py b/scripts/init.py
index c0e94e4..f706f08 100755
--- a/scripts/init.py
+++ b/scripts/init.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 from utils.settings import BASE_DIR, load_config, create_docker_env_file
-from utils.functions import exec_in_container
+from utils.functions import exec_in_container, run
 
 from pathlib import Path
 import shlex
@@ -115,9 +115,13 @@ def init_sqldb( config ):
     from argparse import ArgumentParser
 
     parser = ArgumentParser(
-        description="initialize the repository: create directories, initialize xml database, initialize sql database"
+        description="initialize the repository: download git deps, create directories, initialize xml database, initialize sql database"
     )
-    parser.parse_args()
+    parser.add_argument(
+        "--build",
+        action = "store_true"
+    )
+    args = parser.parse_args()
 
     # orig_config_file -> env_file:
     create_docker_env_file()
@@ -144,4 +148,11 @@ def init_sqldb( config ):
 
     create_dirs( config )
 
+    # rebuild docker image:
+    if args.build:
+        run(
+            env = config,
+            build = True,
+        )
+
     init_sqldb( config )
diff --git a/scripts/run.py b/scripts/run.py
index dc49b43..dd80d3e 100755
--- a/scripts/run.py
+++ b/scripts/run.py
@@ -1,30 +1,13 @@
 #!/usr/bin/env python3
 
 from utils.settings import BASE_DIR, load_config
-# from utils.functions import exec_in_xmldb
+from utils.functions import run
 
 import subprocess
 import shlex
 import os
 from time import sleep
 
-def run(
-        env,
-        cmd=[]
-):
-    if len(cmd) > 0:
-        # run application
-        subprocess.call(
-            shlex.split("docker-compose run webserver") + cmd,
-            env=env
-        )
-    else:
-        # run application
-        subprocess.call(
-            shlex.split("docker-compose up -d"),
-            env=env
-        )
-
 if __name__ == '__main__':
 
     from argparse import ArgumentParser
@@ -34,6 +17,10 @@ def run(
     parser = ArgumentParser(
         description="run the webserver"
     )
+    parser.add_argument(
+        "--build",
+        action = "store_true"
+    )
     parser.add_argument(
         "CMD",
         nargs="*"
@@ -45,5 +32,6 @@ def run(
         (vars(args)['CMD'])
     run(
         env=config,
+        build = args.build,
         cmd=CMD
     )
diff --git a/scripts/utils/functions.py b/scripts/utils/functions.py
index fd39858..c7d1e5c 100644
--- a/scripts/utils/functions.py
+++ b/scripts/utils/functions.py
@@ -4,6 +4,24 @@
 import shlex
 
 
+def run(
+        env,
+        build=False,
+        cmd=[]
+):
+    if len(cmd) > 0:
+        # run application
+        subprocess.call(
+            shlex.split("docker-compose run webserver") + cmd,
+            env=env
+        )
+    else:
+        # run application
+        subprocess.call(
+            shlex.split("docker-compose up -d") + (["--build"] if build else []),
+            env=env
+        )
+
 def exec_in_container(
     *args,
     env