diff --git a/README.md b/README.md
index deaee92c4f7960538c2104fab9eb6093f438ae65..b5ce450bf6ceb5735120e88f39fab5429aa0fd41 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,18 @@ $ jupyter --paths
 ```
 The `config` section from the output lists the directories where your `openbis-connections.yaml` file should be placed.
 
+## install Jupyter extension manually
+
+In most cases, a simple `pip install --upgrade jupyter-openbis-extension` will do. However, in some cases you need to issue the following commands to get the extension running correctly:
+
+```
+$ jupyter serverextension enable --py jupyter-openbis-extension
+$ jupyter nbextension install --py jupyter-openbis-extension --user
+$ jupyter nbextension enable --py jupyter-openbis-extension --user
+```
+
+If you want to install the extension globally, use `--system` instead of `--user`.
+
 ## Launching Jupyter notebook
 
 Now you are ready to launch Jupyter notebook:
@@ -122,4 +134,4 @@ The `-e` is a shortcut for `--editable`. This means, it will only establish a li
 
 If you make modifications on the UI (the Javascript files) you only need to reload the page in order the see the effect.
 
-How to extend Jupyter Notebooks is described [here](https://jupyter-notebook.readthedocs.io/en/stable/extending/index.html). To distribute Jupyter Extensions, read this [documentation](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html#) carefully.
\ No newline at end of file
+How to extend Jupyter Notebooks is described [here](https://jupyter-notebook.readthedocs.io/en/stable/extending/index.html). To distribute Jupyter Extensions, read this [documentation](https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html#) carefully.
diff --git a/README.rst b/README.rst
index 7fa2e19ef7be4038a1f716b8f111a7e731191ecb..1a5654e399c57a995fe2d44e52b4667a89836cea 100644
--- a/README.rst
+++ b/README.rst
@@ -69,6 +69,23 @@ These directories can be found by invoking
 The ``config`` section from the output lists the directories where your
 ``openbis-connections.yaml`` file should be placed.
 
+install Jupyter extension manually
+----------------------------------
+
+In most cases, a simple
+``pip install --upgrade jupyter-openbis-extension`` will do. However, in
+some cases you need to issue the following commands to get the extension
+running correctly:
+
+::
+
+    $ jupyter serverextension enable --py jupyter-openbis-extension
+    $ jupyter nbextension install --py jupyter-openbis-extension --user
+    $ jupyter nbextension enable --py jupyter-openbis-extension --user
+
+If you want to install the extension globally, use ``--system`` instead
+of ``--user``.
+
 Launching Jupyter notebook
 --------------------------
 
@@ -131,9 +148,15 @@ steps:
 After the setup is complete, you'll have
 
 -  Jupyter with openBIS extension running at http://localhost:8888.
--  openBIS running at http://localhost:8122, with credentials
+-  openBIS running at https://localhost:8122/openbis/, with credentials
    admin/password.
--  Experiment /DEFAULT/DEFAULT with a lot of datasets for testing.
+-  Object /DEFAULT/DEFAULT with a lot of datasets for testing.
+
+Hint: Jupyter creates no log file. Everything is printed onto the
+console. In order to see this output do the following: 1. vagrant ssh 2.
+screen -r
+
+You can escape from the screen by typing ^A followed by ^D.
 
 clone repository and install extension for development
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~