Add setup description

README.md

@@ -1,2 +1,226 @@
 # 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.
+
+## 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.
+
+### 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.
+- 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 postgres database
+- all repositories uploaded to the GIN instance
+- configuration files
+- custom frontend files
+
+The following bash script lines are an example how to set up these required directories.
+
+```bash
+# Provide the user that will use docker-compose to start the service
+DEPLOY_USER=[provide username]
+
+# Specify the GIN files root location
+DIR_GINROOT=[provide path to GIN root directory]
+
+# Postgres database password
+PGRES_PASS=[changeMe]
+
+# Prepare a ginservice group if it does not exist
+if [ $(getent group ginservice) ]; then
+  echo "group ginservice already exists."
+else
+  groupadd ginservice
+fi
+
+# Create dedicated "ginuser" user and add it to the "docker"
+# group; and the "ginservice" group; create all required 
+# directories with this user and the "ginservice" group permission.
+if [ $(getent passwd ginuser) ]; then
+    echo "user ginuser already exists"
+else
+    useradd -M -G docker,ginservice ginuser
+    # Disable login for user ginuser
+    usermod -L ginuser
+fi
+
+# Make sure to add the user running docker-compose to the ginservice group as well!
+usermod -a -G ginservice $DEPLOY_USER
+
+# Required directories
+DIR_GINCONFIG=$DIR_GINROOT/config
+DIR_GINVOLUMES=$DIR_GINROOT/volumes
+DIR_GINDATA=$DIR_GINROOT/gindata
+
+# Create gin specific directories
+# The 'notice' directory may contain a banner.md file.
+# The content of this file is displayed on the GIN page without a service restart e.g.
+#  to inform users of an upcoming service downtime.
+mkdir -vp $DIR_GINCONFIG/gogs/notice
+mkdir -vp $DIR_GINCONFIG/postgres
+
+mkdir -vp $DIR_GINVOLUMES/ginweb
+
+mkdir -vp $DIR_GINDATA/gin-repositories
+mkdir -vp $DIR_GINDATA/gin-postgresdb
+
+mkdir -vp $DIR_GINROOT/gin-dockerfile
+
+# Create an env file to specify the docker compose project name
+echo "COMPOSE_PROJECT_NAME=gin" > $DIR_GINROOT/gin-dockerfile/.env
+
+# Create postgres secret file
+echo "POSTGRES_PASSWORD=${PGRES_PASS}" > $DIR_GINCONFIG/postgres/pgressecrets.env
+```
+
+### Prepare docker-compose file
+
+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.
+
+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 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/..`
+
+### Adjust file permissions
+
+Change all file permissions of the GIN root directory to ginservice group to ensure the docker services 
+have access to the directories and change group permissions to write.
+
+```bash
+chown -R ginuser:ginservice $DIR_GINROOT
+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 
+`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
+    ```
+
+- 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
+    ```
+
+- 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.
+    - db:               postgres
+    - host:             ginpgres:5432
+    - user:             gin
+    - password:         [used during database setup]
+    - database name:    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.
+- save; this might redirect to an error page, but this is inconsequential
+- check that the page is running at your specified domain
+
+- stop all docker containers
+    ```bash
+    cd $DIR_GINROOT/gin-dockerfile
+    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.
+    - 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.
+    - in the [security] section, copy the SECRET_KEY value from the automatically create app.ini to this one.
+
+- copy the `public` and `templates` directories of this repository to `$DIR_GINROOT/config/gogs`; this directory 
+  is specified via the `docker-compose.yml` file to hold custom frontend templates for the GIN instance. When the 
+  container is started, templates and stylesheets from these directories will overrule same-name files on the server.
+  - `home.tmpl` is the main page non-logged in users will see.
+  - `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
+
+- adjust file permissions for all added and modified files on the server
+    ```bash
+    chown -R ginuser:ginservice $DIR_GINCONFIG
+    ```
+
+- stop any running container and restart the full service
+    ```bash
+    docker-compose down
+    docker-compose up -d
+    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 
+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:
+
+On your GIN instance 
+- create a `Service` organisation
+- create a `Service/Info` repository, do not initialize it!
+- set this repo to public
+- go to the 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"
+  - "About" refers to the page "http://[domain]/Service/Info/wiki/about.md"
+  - "Imprint" refers to the page "http://[domain]/Service/Info/wiki/imprint.md"
+  - "Contact" refers to the page "http://[domain]/Service/Info/wiki/contact.md"
+  - "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 
+  the wiki repository after it has been initialized:
+  `git clone ssh://git@[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 
+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: 
+
+- 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
+gin add-server --web https://gin.dev.g-node.org:443 --git git@gin.dev.g-node.org:2121 alias-in-house
+gin use-server alias-in-house
+gin login
+```