[README] Clarify docker-compose setup desc

README.md

@@ -23,9 +23,13 @@ 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. 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 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. 
@@ -91,21 +95,27 @@ But it comes with notes on persistent storage, server customization and notes on
 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.
+
+This setup will require the files found in the [in-house-gin](https://gin.g-node.org/G-Node/in-house-gin) repository. 
+It also assumes, that the service will run behind an http server like [Apache](https://httpd.apache.org/). If you still 
+want to test the docker-compose setup on a local machine, you will need to make adjustments to the docker-compose.yml 
+file e.g. mapping port 3000 to make it available.
+
 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 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.
+- 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 have started. These directories 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
@@ -191,6 +201,9 @@ echo "COMPOSE_PROJECT_NAME=gin" > $DIR_GINROOT/gin-dockerfile/.env
 echo "POSTGRES_PASSWORD=${PGRES_PASS}" > $DIR_GINCONFIG/postgres/pgressecrets.env
 ```
 
+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.
+
 #### Prepare docker-compose file
 
 The `resources` folder contains an example docker-compose file to set up an in-house GIN instance.
@@ -200,11 +213,15 @@ file assumes the directory structure created above to properly map all required
 
 Update the docker-compose file to match your requirements:
   - adjust `web:environment`: use the IDs of the prepared `ginuser` and `ginservice` group
-  - make sure the ssh port is set correctly: use e.g. port 2121:22 since server port 22 needs to be available for normal ssh connections
+  - make sure the ssh port is set correctly: use e.g. port 2121:22 since server port 22 needs to be available 
+    for normal ssh connections
   - make sure the set IP matches the IP set in your apache2/webserver configuration
   - ensure the following paths are set correctly to match the created directory structure
     - `web:volumes: ../gindata/..`
     - `db:volumes: ../gindata/..`
+  - if you plan to run the docker-compose setup on localhost you also need to map the port 3000 in the docker-compose 
+    file; if you use an http server like an apache do not expose the port via the docker-compose file but include it 
+    in the apache configuration.
 
 #### Adjust file permissions
 
@@ -242,7 +259,12 @@ You can use the `gnode/gin-web:latest` docker container to run the in-house GIN;
 - 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.
 
-- on the setup page, set the following fields with the corresponding values. For other setup options please refer to the gogs documentation.
+  ```
+  docker-compose up -d
+  ```
+
+- on the setup page, set the following fields with the corresponding values. For other setup options please refer 
+  to the gogs documentation.
     - db:               postgres
     - host:             ginpgres:5432
     - user:             gin
@@ -251,9 +273,10 @@ You can use the `gnode/gin-web:latest` docker container to run the in-house GIN;
     - app name:         GIN dev
     - repo root:        as defined in `docker-compose` on the container side e.g. `/data/repos`
     - domain:           your domain or localhost
-    - create an administration user; do not use 'admin'; if the database is restored from the live server, this user will be overwritten.
+    - create an administration user; do not use 'admin'; if the database has been restored from a live server, 
+      this user will be overwritten.
 - save; this might redirect to an error page, but this is inconsequential
-- check that the page is running at your specified domain
+- check that the server is running at your specified domain and you can login with the created admin user
 
 - stop all docker containers
   ```bash
@@ -261,9 +284,10 @@ You can use the `gnode/gin-web:latest` docker container to run the in-house GIN;
   docker-compose down
   ```
 
-
-- replace `config/gogs/conf/app.ini` with the file found in `resources/app.ini`; when in doubt keep the old file and compare entries.
-  - adjust all settings to fit your server requirements - the example `app.ini` should fit most settings and directories used so far.
+- replace `config/gogs/conf/app.ini` with the file found in `resources/app.ini`; when in doubt keep the old file and 
+  compare entries.
+  - adjust all settings to fit your server requirements - the example `app.ini` should fit most settings and 
+    directories used so far.
     - in the [server] section check `DOMAIN`, `HTTP_PORT` and `ROOT_URL`
     - in the [mail] section enable or disable a mail server. Depending on the state of the mailserver, 
       you might want to activate or deactivate registration confirmation by mail.
@@ -346,9 +370,9 @@ 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:
+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
@@ -357,18 +381,20 @@ 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 from the root of the repository):
+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 
+root of the repository:
 ```bash
 docker build -t [organization-name]/[container-name] .
 ```
 
 ## Ansible galaxy in-house-gin
 
-Mika Pflüger was so kind to create an Ansible role for in-house-gin. If you want to give it a try, you can find the details over at the [ansible galaxy page](https://galaxy.ansible.com/mikapfl/gin_ansible_role). We take neither credit nor responsibility for this project.
+Mika Pflüger was so kind to create an Ansible role for in-house-gin. If you want to give it a try, you can find the 
+details over at the [ansible galaxy page](https://galaxy.ansible.com/mikapfl/gin_ansible_role). We take neither 
+credit nor responsibility for this project.
 
 ## 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)
-