Document ssh access

README.md

@@ -3,7 +3,7 @@
 WissKI-Distillery is a Docker-based server provisioning and managing for multiple
 [WissKI](https://wiss-ki.eu/) instances.
 
-The  WissKI Distillery is a set of scripts, tools, and applications that allows to operate
+The WissKI Distillery is a set of scripts, tools, and applications that allows to operate
 a WissKI cloud of distinct but jointly managed WissKI instances, hosted on a dedicated
 hardware pool. Like the WissKI system, the WissKI Distillery is open source and free to
 use.
@@ -58,37 +58,39 @@ 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. 
+  - 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.
-    - See [distillery/resources/compose/web](distillery/resources/compose/web) for implementation details. 
+  - 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. 
+  - It is configured to run inside a docker container
-    - A `bookkeeping` database and table is created by default, to store known WissKI instance metadata in. 
+  - A passwordless `root` account is created, which can only be used from inside the container.
-    - A database shell can be opened using `sudo /distillery/mysql.sh`. 
+  - A `bookkeeping` database and table is created by default, to store known WissKI instance metadata in.
-    - A [phpmyadmin](https://www.phpmyadmin.net/) is started on `127.0.0.1:8080`. 
+  - A database shell can be opened using `sudo /distillery/mysql.sh`.
-    - See [distillery/resources/compose/sql](distillery/resources/compose/sql) for implementation details. 
+  - A [phpmyadmin](https://www.phpmyadmin.net/) is started on `127.0.0.1:8080`.
+  - 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`. 
+  - It is configured to run inside a docker container.
-    - Security is not enabled at the moment. 
+  - The Workbench API is started on `127.0.0.1:7200`.
-    - See [distillery/resources/compose/triplestore](distillery/resources/compose/triplestore) for implementation details. 
+  - Security is not enabled at the moment.
+  - See [distillery/resources/compose/triplestore](distillery/resources/compose/triplestore) for implementation details.
 
 - [proxyssh](https://github.com/tkw1536/proxyssh) - an ssh server that delegates client connections to different WissKIs
-    - It is configured to run inside a docker container
+  - It is configured to run inside a docker container
-    - Uses a global configurable authorized_keys file. 
+  - Uses a global configurable authorized_keys file.
-    - Also allows users to write their own authorized_keys files. 
+  - Also allows users to write their own authorized_keys files.
 
 To manage multiple docker containers, this script makes heavy use of [docker-compose](https://docs.docker.com/compose/).
 
@@ -112,9 +114,9 @@ This can be done using:
 sudo bash /distillery/system_update.sh
 ```
 
-## Provisioning a new WissKI instance  -- 'provision.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,18 +342,17 @@ if you follow the following conditions:
 
 This also applies if you only run a backend service based on this software.
 
-
 ## TODO
 
 - User-level documentation
-    - What is a factory?
+  - What is a factory?
-    - Why a factory?
+  - Why a factory?
-    - First steps after provisioning
+  - First steps after provisioning
 - Automatically setup SALZ adapter (if this is possible)
 - Enable authentication for GraphDB
 - Investigate support for GraphDB Auth in WissKI Salz
-    - Eventually enable security if needed
+  - Eventually enable security if needed
-    - Switch to a different TripleStore altogether?
+  - Switch to a different TripleStore altogether?
 - Investigate managing phpmyadmin
 - Investigate managing graphdb
 - Investigate delegating shell access