Update README

README.md

@@ -1,28 +1,137 @@
 # in-house-gin
 
 This repository documents how to set up a custom instance of the [GIN](https://gin.g-node.org) G-Node infrastructure 
-service.
+service. The project's source code of can be found on [github](https://github.com/G-Node/gogs).
 
-## Setup prerequisites and preparations
+## Set up GIN in your lab
+If you plan to set up a GIN Server in your own lab, you are more than welcome to do so. All our software is based on 
+open source projects and therefore meant to be used, extended and modified by others. The features we implemented on 
+top of [gogs](https://gogs.io/) are available on [Github](https://github.com/G-Node/gogs).
+
+Should you have problems or questions in the process, contact us at [gin@g-node.org](mailto:gin@g-node.org). 
+Even if you have no trouble, we would love to receive your feedback or just learn from you that you have just set up 
+your own GIN! 
+
+### Setup prerequisites and preparations
 
 `docker` and `docker-compose` are required on the system. If the gin instance should be available within the network 
 or to the outside, we recommend using the GIN instance together with an Apache2 server.
+Please see the corresponding installation notes for [docker](https://docs.docker.com/get-docker/) and 
+[docker-compose](https://docs.docker.com/compose/install/) for details. Furthermore, a 
+[dockerhub account](https://hub.docker.com/) is useful.
+
+
+## Test deploying GIN using docker on your local machine
+
+If you are new to docker and docker-compose or deploying services with it, it might be good to test the deployment with 
+a simplified setup using `docker` on your local machine. For a description on how to deploy a full server with customized
+content, please see the section "Deploy and run full server" below.
+
+### Set up GIN with Docker
+The easiest way to set up a GIN server is via pre-built docker containers. You will need a working Docker installation. 
+
+You start by downloading the docker image for GIN by typing:
+```bash
+docker pull gnode/gin-web:latest
+```
+
+You can start GIN with:
+```bash
+docker run -p 3000:3000 -p 2222:22 -d gnode/gin-web
+```
+You can now visit the website of your GIN server at port 3000 (see the first -p above) of your local machine (localhost:3000). 
+The ssh port can be reached via port 2222 (see the second -p above). You will be greeted with a setup page which will 
+ask you for all the necessary information.
+
+This will map all data and configuration into the docker container, which is fine for playing around. However, should 
+you want to use the server for data it's probably not what you want. Instead, we probably want to map the data as well 
+as the config and log files into some folder of your local host:
+```bash
+docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -d gnode/gin-web
+```
+
+This will map the data, configs and such into a folder on your machine (please change "somefolder" accordingly).
+
+If you want the container to run the web service with another user and group id than 1000, you can do this by setting 
+the corresponding environment variables on docker by running:
+```bash
+docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -e GITUID="1001" -e GITGID="1001" -d gnode/gin-web
+```
+
+where `GITUID` and `GITGID` are followed by the numerical user and group ids respectively.
+
+### Update an existing container
+To update an existing GIN docker installation you simply need to pull in the changes:
+```bash
+docker pull gnode/gin-web:latest
+```
+
+afterward, you stop the running instance with:
+```bash
+docker stop <containername>
+```
+
+`<containername>` can be determined with:
+
+```bash
+docker ps
+```
+
+After that you can start a new version using the same command that you started the original docker container with, e.g.:
+
+```bash
+docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -d gnode/gin-web
+```
+
+
+## Deploy and run a full server using docker-compose
+
+The setup for a full server requires `docker-compose` and is more complex than the simple, local `docker` setup.
+But it comes with notes on persistent storage, server customization and notes on how to configure the GIN client
+to work with your own instance of GIN.
+If you are considering this option, it might still be worth to try setting up the local version above as described 
+above to familiarize yourself with the basic GIN setup before diving into the more complex one.
+All the necessary steps should be described and available below. If you still find steps missing or the description 
+ambiguous, please let us know at [gin@g-node.org](mailto:gin@g-node.org).
+
+This setup will require the files found in the [in-house-gin](https://gin.g-node.org/G-Node/in-house-gin) repository.
 
 ### Required group and user
 To smoothly work with a docker deployment, the following groups and users should be set up.
-- prepare dedicated deployment group e.g. "ginservice" group if it does not exist
-- create a dedicated deployment user e.g. "ginuser"
-- for any further setup, all required directories and files should be created with this user/group as owners.
+- prepare a dedicated deployment group e.g., "ginservice" group if it does not exist.
+- create a dedicated deployment user e.g., "ginuser".
+- for any further setup, all required directories and files should be created with this user/group as owner.
 - make sure to add all users that are running docker-compose or need access to project files to the docker and deploy groups.
 
 ### Required directories
 
-The current setup requires certain directories to be available before the containers are started. These files will contain and persist
+The current setup requires certain directories to be available before the containers have started. These directories will contain and persist
 - the postgres database
 - all repositories uploaded to the GIN instance
 - configuration files
 - custom frontend files
 
+This schema notes all required directories and files:
+```
+$GIN_ROOT_FOLDER
+├── config
+|   ├── postgres
+|   |   └── pgressecrets.env
+|   └── gogs
+|       ├── notice
+|       |   └── banner.md   # GIN page notice banner
+|       ├── public          # custom frontend style
+|       └── templates       # custom frontend files
+├── volumes
+|   └── ginweb
+├── gindata
+|   ├── gin-postgresdb
+|   └── gin-repositories
+└── gin-dockerfile
+    ├── .env
+    └── docker-compose.yml
+```
+
 The following bash script lines are an example how to set up these required directories.
 
 ```bash
@@ -84,7 +193,7 @@ echo "POSTGRES_PASSWORD=${PGRES_PASS}" > $DIR_GINCONFIG/postgres/pgressecrets.en
 
 ### Prepare docker-compose file
 
-The `resources` folder contains an example docker-compose file to set up an in-house gin instance.
+The `resources` folder contains an example docker-compose file to set up an in-house GIN instance.
 
 Prepare the `docker-compose.yml` file in the `$DIR_GINROOT/gin-dockerfile` directory. The example docker-compose 
 file assumes the directory structure created above to properly map all required volumes.
@@ -109,26 +218,26 @@ chmod -R g+rw $DIR_GINROOT
 
 ### Docker container and initial GIN setup
 
-You can use the gnode/gin-web:latest docker container to run the in-house gin - this set by default in the example 
+You can use the `gnode/gin-web:latest` docker container to run the in-house GIN; this is set as default in the example 
 `docker-compose.yml` file but can be changed to another container.
 
 - fetch all required containers from the docker-gin directory
-    ```bash
-    cd $DIR_GINROOT/gin-dockerfile
-    docker-compose pull
-    ```
+  ```bash
+  cd $DIR_GINROOT/gin-dockerfile
+  docker-compose pull
+  ```
 
 - launch the postgres database container for the initial gin setup
-    ```bash
-    docker-compose up -d db
-    docker exec -it gin_db_1 /bin/bash
-    su -l postgres
-    createuser -P gin
-    # enter a password for the new role and note it; it will later be used on the initial gin setup page
-    createdb -O gin gin
-    exit
-    exit
-    ```
+  ```bash
+  docker-compose up -d db
+  docker exec -it gin_db_1 /bin/bash
+  su -l postgres
+  createuser -P gin
+  # enter a password for the new role and note it; it will later be used on the initial gin setup page
+  createdb -O gin gin
+  exit
+  exit
+  ```
 
 - launch the gin web docker container for the inital setup; on a local machine it should be accessible in the webbrowser 
   at localhost:3000; if it is set up within a network or via a domain name, it will be available there.
@@ -166,7 +275,9 @@ You can use the gnode/gin-web:latest docker container to run the in-house gin -
   - `base/head_gin.tmpl` contains custom links in the page header
   - `base/footer_gin*.tmpl` templates contain custom entries in the page.
   - `explore/navbar.tmpl` contains categories on the `explore` page.
-  - for more details on custom content please see the "Customize the in-house GIN content" section below
+  - for additional custom content changes please see the "Customize the in-house GIN content" section below
+  - note that every time the content of the `public` or `tempaltes` folder have been changed, the docker container
+    needs to be restarted before the changes take effect.
 
 - adjust file permissions for all added and modified files on the server
     ```bash
@@ -180,22 +291,23 @@ You can use the gnode/gin-web:latest docker container to run the in-house gin -
     docker-compose logs -f
     ```
 
-NOTE: when working with GIN (gin.g-node.org) and a local version it can happen, 
-that the services have set up different csrf tokens. This results in the message `Invalid csrf token.` 
-when submitting any form via the web browser. In this case either purge the browser cache or use a different 
+NOTE: when working with the GIN server (gin.g-node.org) in parallel with a local or in-house version of GIN it can happen, 
+that the services have set up different CSRF tokens. This results in the message `Invalid csrf token.` when submitting 
+any webform data via the web browser. In this case either purge the browser cache or use a different 
 browser all-together.
 
 ### Customize the in-house GIN content
 
-To change the content of the `Help`, `News`, `about`, `imprint`, `contact`, `terms of use` and `Datenschutz` pages as 
-well as the instance wiki, you will need to provide a specific gin group and repository; ideally with an administrative 
-gin user:
+Apart from changing the main page, as well as header and footer content as described above, most custom pages are hosted 
+via the Wiki of a specific GIN repository wiki: `Service/Info`. By default the service links and expects the following
+pages in this particular wiki: `Help`, `News`, `about`, `imprint`, `contact`, `terms of use` and `Datenschutz`.
 
-On your GIN instance 
+To create and edit these on your GIN instance 
+- log in with an administrative user
 - create a `Service` organisation
-- create a `Service/Info` repository, do not initialize it!
+- create a `Service/Info` repository
 - set this repo to public
-- go to the repos wiki page and initialise the wiki by creating a "home.md" page.
+- open this repos' wiki page and initialise the wiki by creating a "home.md" page.
 - all files required by default can be added via the wiki of this repository at the address "http://[domain]/Service/Info/wiki"
   - "Help" refers to the page "http://[domain]/Service/Info/wiki/Home.md"
   - "News" refers to the page "http://[domain]/Service/Info/wiki/News.md"
@@ -205,18 +317,18 @@ On your GIN instance
   - "Terms of use" refers to the page "http://[domain]/Service/Info/wiki/Terms of use.md"
   - "Datenschutz" refers to the page "http://[domain]/Service/Info/wiki/Datenschutz.md"
 
-- these files can be added via the web wiki; alternatively you can add an ssh key to your user and git clone 
+- alternatively to adding these pages via the web interface, you can add an ssh public key to your user and git clone 
   the wiki repository after it has been initialized:
-  `git clone ssh://git@[domain]:2121/Service/Info.wiki.git`
+  `git clone ssh://git@[your domain]:2121/Service/Info.wiki.git`
 
 ### GIN client setup
 
-By default the [GIN-client](https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Setup), a commandline tool to work with gin, 
-is set up to work with GIN at gin.g-node.org. To use the GIN-Client with an in-house version of gin a couple of 
+By default the [GIN-client](https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Setup), a command line tool to work with GIN, 
+is set up to work with the GIN server at gin.g-node.org. To use the GIN-Client with an in-house version of gin a couple of 
 additional steps have to be taken. On the machine where a gin client is installed, additional entries can be added to 
-the list of supported servers: 
+the list of supported servers.
 
-- please note, that you will need to add the port number that is specified as the ssh port in the `docker-compose.yml` file. 
+Please note, that you will need to add the port number that is specified as the ssh port in the `docker-compose.yml` file. 
   In the example this has been set to 2121. The name "alias-in-house" can of course be chosen freely.
 ```bash
 gin logout
@@ -224,3 +336,28 @@ gin add-server --web https://gin.dev.g-node.org:443 --git git@gin.dev.g-node.org
 gin use-server alias-in-house
 gin login
 ```
+
+### Avoid exposing debug service
+
+Macaron toolbox, which runs alongside GOGS, exposes a minimal debug control panel at `/debug` (https://github.com/gogs/gogs/issues/5578).  
+This control panel can be used to run profiling operations and dump information about the running server.  Currently, 
+there's no way to restrict this in code. For now, adding the following Apache configuration will deny all access to the 
+console:
+```
+<Location /debug>
+    Deny from  all
+</Location>
+```
+
+### Build your own docker container from source
+
+If the customizations above are not sufficient for your service, you can also clone our [GIN github repository](https://github.com/G-Node/gogs), 
+directly edit the source code and build your own docker container (run from the root of the repository):
+```bash
+docker build -t [organization-name]/[container-name] .
+```
+
+### Further reading
+
+Since GIN is based on GOGS, the official documentation for running GOGS in a container is also relevant:
+[Docker for GOGS](https://github.com/gogs/gogs/tree/main/docker)