بدون توضیح

M. Sonntag 3bbd82e712 Add setup description		2 سال پیش
public	82f5f3b2d9 Add custom style	2 سال پیش
resources	9a2ffd4f08 Update docker-compose	2 سال پیش
templates	0a1f4260d1 Add custom templates	2 سال پیش
.gitignore	9ae126d2d2 Add gitignore	2 سال پیش
LICENSE	48e00e7338 Initial commit	2 سال پیش
README.md	3bbd82e712 Add setup description	2 سال پیش

in-house-gin

This repository documents how to set up a custom instance of the GIN 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.

# 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.

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

cd $DIR_GINROOT/gin-dockerfile
docker-compose pull

launch the postgres database container for the initial gin setup

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
```
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
```
chown -R ginuser:ginservice $DIR_GINCONFIG
```
stop any running container and restart the full service
```
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, 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

README.md