Document ssh access

README.md

@@ -58,20 +58,21 @@ vagrant up
 vagrant ssh -- -L 7200:127.0.0.1:7200 -L 8080:127.0.0.1:8080
 ```
 
-
 ## Preparing the Server -- 'system_install.sh'
 
-*TLDR: `sudo bash /distillery/system_install.sh /path/to/graphdb.zip`*
+_TLDR: `sudo bash /distillery/system_install.sh /path/to/graphdb.zip`_
 
 To prepare the server for becoming a WissKI factory, several core Docker Instances must be installed.
 These are:
 
 - [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) - an automated nginx reverse proxy
+
   - This will delegate individual hostnames to appropriate docker containers, see [this blog post](http://jasonwilder.com/blog/2014/03/25/automated-nginx-reverse-proxy-for-docker/) for an overview.
   - Optionally makes use of [docker-letsencrypt-nginx-proxy-companion](https://github.com/nginx-proxy/docker-letsencrypt-nginx-proxy-companion) to automatically provision and renew HTTPS certificates.
   - See [distillery/resources/compose/web](distillery/resources/compose/web) for implementation details.
 
 - [MariaDB](https://mariadb.org/) - an SQL server
+
   - It is configured to run inside a docker container
   - A passwordless `root` account is created, which can only be used from inside the container.
   - A `bookkeeping` database and table is created by default, to store known WissKI instance metadata in.
@@ -80,6 +81,7 @@ These are:
   - See [distillery/resources/compose/sql](distillery/resources/compose/sql) for implementation details.
 
 - [GraphDB](http://graphdb.ontotext.com/) - a SPARQL backend for WissKI
+
   - It is configured to run inside a docker container.
   - The Workbench API is started on `127.0.0.1:7200`.
   - Security is not enabled at the moment.
@@ -114,7 +116,7 @@ sudo bash /distillery/system_update.sh
 
 ## Provisioning a new WissKI instance -- 'provision.sh'
 
-*TLDR: `sudo /distillery/provision.sh slug-of-new-website`*
+_TLDR: `sudo /distillery/provision.sh slug-of-new-website`_
 
 A new WissKI instance consists of several components:
 
@@ -131,24 +133,24 @@ The given domain can be configured within the '.env' file.
 
 We use the following process to provision a new instance:
 
-__1. Create a new docker-compose.yml file__
+**1. Create a new docker-compose.yml file**
 
 In this step we first create a directory on the real system to hold all files relating to this instance.
 By default, this takes place inside `/var/www/deploy/instances/$DOMAIN`, but this can be configured.
 We then create a docker-compose file in this directory that is ready for running the `barrel` container.
 
-__2. Create an appropriate SQL database and user__
+**2. Create an appropriate SQL database and user**
 
 We create a new SQL database to eventually store Drupal-related data in.
 The user and database names are generated from the slug.
 The database password is randomly generated and only made available directly to the Drupal instance later.
 
-__3. Create a GraphDB repository and user__
+**3. Create a GraphDB repository and user**
 
 Next, we create a dedicated GraphDB repository for the WissKI instance.
 We also create a new GraphDB user with access to this repository.
 
-__4. Provision the instance inside the container__
+**4. Provision the instance inside the container**
 
 We start the container in provisioning mode.
 
@@ -162,8 +164,7 @@ This does the following:
 Currently the WissKI Salz instance is not enabled programatically.
 Instead all credentials (along with instructions on how to configure it) are printed to the command line.
 
-
+**6. Start the Docker Container**
-__6. Start the Docker Container__
 
 Finally, we can start the docker container.
 
@@ -179,7 +180,6 @@ sudo bash /distillery/provision.sh SLUG
 Sometimes it becomes necessary (because of changes to this project) to rebuild the docker image running a certain docker instance.
 To do so, use:
 
-
 ```bash
 sudo bash /distillery/rebuild.sh SLUG
 ```
@@ -204,17 +204,14 @@ Sometimes it is useful to reserve a particular instance name.
 This is done by hosting a placeholder website at the domain.
 To do so, use:
 
-
 ```bash
 sudo bash /distillery/reserve.sh SLUG
 ```
 
 To un-reserve a website, manually stop the docker stack and remove the folder.
 
-
 ## Purge an existing WissKI instance -- 'purge.sh'
 
-
 Sometimes it is required to remove a given WissKI instance.
 In particular all parts belonging to it should be removed.
 
@@ -254,6 +251,7 @@ sudo bash /distillery/backup.sh
 
 Backups are stored in the `backups/final` directory.
 They contain:
+
 - a filesystem backup of all instances
 - a complete backup of the SQL database
 - nquads of all the GraphDB repositories
@@ -272,7 +270,42 @@ MAILTO="some-admin-email@example.com"
 
 ## SSH Access
 
-- to be documented
+The distillery exposes an ssh daemon for users to access individual WissKI Shells.
+It is running on port 2222 by default.
+
+To access a shell in a particular barrel set the username equal to the slug.
+For instance, to gain access to a shell inside a WissKI instance with a slug `porcelain` use the following command line:
+
+```bash
+ssh -p 2222 porcelain@localhost
+```
+
+Replace `localhost` with the hostname of the WissKI Distillery.
+
+Inside the container, normal shell acess is provided. 
+Both `drush` and `composer` are available. 
+No technical reasons using `sudo` or switching to `root` is not possible. 
+
+### Authentication
+
+Authentication is performed using SSH Keys.
+Within each instance, ssh keys can be added to the file `/var/www/.ssh/authorized_keys` using the default OpenSSH `authorized_keys` format.
+
+Furthermore, global ssh Keys (that have access to every instance) can be added to a `GLOBAL_AUTHORIZED_KEYS_FILE`. This is set in the Distillery `.env` file, and defaults to `/distillery/authorized_keys/`.
+
+### Port Forwarding
+
+In order to access the __GraphDB Workbench__ or __phpmyadmin__ ssh port forwarding can be used.  
+GraphDB is running on the host `triplestore` on port `7200`. 
+PhpMyAdmin is running on the host `phpmyadmin` on port `8080`. 
+
+To forward both you can use a command such as:
+
+```bash
+ssh -p 2222 -L localhost:7200:triplestore:7200 -L localhost:8080:phpmyadmin:8080 porcelain@localhost
+```
+
+This will make GraphDB and PhpMyAdmin available at `localhost:7200` and `localhost:8080` for the duration of the connection. 
 
 ## License
 
@@ -309,7 +342,6 @@ if you follow the following conditions:
 
 This also applies if you only run a backend service based on this software.
 
-
 ## TODO
 
 - User-level documentation