|
@@ -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
|
|
|
+```
|