some more words

components/taupage.rst

@@ -72,6 +72,8 @@ configuration format::
      - 22
 
 Provide this configuration as your user-data during launch of your EC2 instance.
+You can use the ``TaupageConfig`` section of :ref:`senza`'s ``TaupageAutoScalingGroup``
+to easily pass Taupage options when deploying with Senza.
 
 application_id:
 -----------------
@@ -209,6 +211,6 @@ TODO
 Managed SSH access
 ------------------
 
-SSH access is managed with the SSH access granting service. The AMI is set up to have automatic integration. Your
+SSH access is managed with the :ref:`even` SSH access granting service. The AMI is set up to have automatic integration. Your
 SSH key pair choice on AWS will be ignored - temporary access can only be gained via the granting service. All user
-actions are logged for auditing reasons.
+actions are logged for auditing reasons. See the :ref:`ssh-access` section in the User's Guide for details.

user-guide/application-development.rst

@@ -7,7 +7,7 @@ To be written...
 * Applications should be developed as microservices which focus on small tasks.
 * Applications should follow the `Twelve-Factor App Principle`_.
 * Application APIs shoud be RESTful
-* Applications should be deployed as Docker artifacts
+* Applications must be deployed as Docker artifacts
 
 
 Docker
@@ -42,12 +42,32 @@ Example:
 .. code-block:: json
 
     {
-    "url": "git:git@github.com:zalando/bastion-host.git",
-    "revision": "cd768599e1bb41c38279c26254feff5cf57bf967",
-    "author": "hjacobs",
-    "status": ""
+        "url": "git:git@github.com:zalando/bastion-host.git",
+        "revision": "cd768599e1bb41c38279c26254feff5cf57bf967",
+        "author": "hjacobs",
+        "status": ""
     }
 
+An example implementation on how to generate the ``scm-source.json`` file with Bash:
+
+.. code-block:: bash
+
+    #!/bin/bash
+    REV=$(git rev-parse HEAD)
+    URL=$(git config --get remote.origin.url)
+    STATUS=$(git status --porcelain)
+    if [ -n "$STATUS" ]; then
+        REV="$REV (locally modified)"
+    fi
+    # finally write hand-crafted JSON to scm-source.json
+    echo '{"url": "git:'$URL'", "revision": "'$REV'", "author": "'$USER'", "status": "'$STATUS'"}' > scm-source.json
+
+Logging
+=======
+
+Applications should log to STDOUT. The runtime environment (:ref:`Taupage`) will do appropriate log shipping to a central log UI provider.
+Application logs must not contain any personal and/or sensitive information such as customer data, credentials or similar.
+
 
 .. _Twelve-Factor App Principle: http://12factor.net/
 .. _Zalando Ubuntu Docker base image: https://registry.hub.docker.com/u/zalando/ubuntu/

user-guide/ssh-access.rst

@@ -24,3 +24,7 @@ You can overwrite settings on the command line:
     $ piu -O odd-eu-west-1.myotherteam.example.org 172.31.1.1 test
 
 
+.. Caution::
+
+    All user actions are logged for auditing reasons, therefore all **SSH sessions must be kept free of
+    any sensitive and/or personal information**.

user-guide/troubleshooting.rst

@@ -2,6 +2,19 @@
 Troubleshooting
 ===============
 
+Permission issues when running Docker container on Taupage AMI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you get permission issues (e.g. ``chown: changing ownership of foobar: Operation not permitted``) when running your Docker image on Taupage,
+you probably run a Docker image assuming to run as ``root``. Taupage starts Docker containers with an unprivileged user by default.
+You can test your Docker image locally with ``docker run -u 998 ...``.
+Usually all apps (especially JVM-based applications) should be able to run as non-root.
+Sadly most Docker images from the official Docker Hub assume running as root.
+
+
+If you really need to run your Docker container as ``root``, you can use the ``root: true`` Taupage config option.
+See the :ref:`Taupage reference <taupage>` for details.
+
+
 I cannot access my EC2 instance via SSH
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~