[README] Docker vs compose clarification

README.md

@@ -23,16 +23,20 @@ Please see the corresponding installation notes for [docker](https://docs.docker
 
 ## 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.
+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. This deployment is meant as a means to explore the web
+frontend of the service.
 
-If you are not familiar with docker or docker-compose, please get familiar with it. These setup notes try to be very 
-thorough, but differences in host machine setup can lead to issues during the service setup process. Decent knowledge 
+For a description on how to deploy a full server including a persistent postgres database and customized content,
+please see the section "Deploy and run full server" below.
+
+If you are not familiar with docker or docker-compose, please get familiar with it. These setup notes try to be very
+thorough, but differences in host machine setup can lead to issues during the service setup process. Decent knowledge
 with docker and docker-compose are usually enough to resolve these issues on your own.
 
 #### 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. 
+The easiest way to set up a GIN web frontend 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
@@ -47,14 +51,21 @@ You can now visit the website of your GIN server at port 3000 (see the first -p
 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.
 
+To make the start as easy as possible, select 'SQLite3' as database. This will setup a lightweight database within the
+docker container for testing purposes. In production use a postgres database as described in the section "Deploy and 
+run full server" below.
+All other settings can be left with their default value to initialize a test GIN server. Note that if an admin account 
+is not specified on the "First-time Run" page, the first account registered on the running service will become a 
+service admin. Also note that username "admin" is reserved and cannot be used.
+
 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:
+you want to use the server for data, it's probably not what you want. Instead, repository data as well as the 
+GIN service config and log files can be mapped to directories of the 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).
+This will map the data, configs and such into a directory on the host machine (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:
@@ -87,6 +98,15 @@ After that you can start a new version using the same command that you started t
 docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -d gnode/gin-web
 ```
 
+#### Using git with a local docker test setup
+
+- add an ssh public key on the running GIN server
+- clone repositories when testing on localhost using
+
+  ```bash
+  git clone ssh://git@localhost:2222/[ginuser]/[ginrepository].git
+  ```
+
 
 ## Deploy and run a full server using docker-compose
 
@@ -202,7 +222,7 @@ echo "POSTGRES_PASSWORD=${PGRES_PASS}" > $DIR_GINCONFIG/postgres/pgressecrets.en
 ```
 
 If the user running the docker containers is not the `ginuser`, it might be worth adding this user to both the `docker` 
-and `ginservice` group as well. Otherwise the services might run into permission issues.
+and `ginservice` group as well. Otherwise, the services might run into permission issues.
 
 #### Prepare docker-compose file
 
@@ -238,7 +258,8 @@ chmod -R g+rw $DIR_GINROOT
 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
+- fetch all required containers from the docker-gin directory; note that this will pull the appropriate docker
+  containers for the GIN web service and the postgres database.
   ```bash
   cd $DIR_GINROOT/gin-dockerfile
   docker-compose pull
@@ -317,8 +338,8 @@ You can use the `gnode/gin-web:latest` docker container to run the in-house GIN;
   docker-compose logs -f
   ```
 
-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 
+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 web browser 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.
 
@@ -370,7 +391,7 @@ 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. 
+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:
 ```
@@ -382,7 +403,7 @@ all access to the console:
 ## 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 it from the 
+https://github.com/G-Node/gogs), directly edit the source code and build your own docker container. Run it from the 
 root of the repository:
 ```bash
 docker build -t [organization-name]/[container-name] .