in-house-gin
This repository documents how to set up a custom instance of the GIN G-Node infrastructure
service. The project's source code of can be found on github.
Set up GIN in your lab
If you plan to set up a GIN Server in your own lab, you are more than welcome to do so. All our software is based on
open source projects and therefore meant to be used, extended and modified by others. The features we implemented on
top of gogs are available on Github.
Should you have problems or questions in the process, contact us at gin@g-node.org.
Even if you have no trouble, we would love to receive your feedback or just learn from you that you have just set up
your own GIN!
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.
Please see the corresponding installation notes for docker and
docker-compose for details. Furthermore, a
dockerhub account is useful.
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.
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.
You start by downloading the docker image for GIN by typing:
docker pull gnode/gin-web:latest
You can start GIN with:
docker run -p 3000:3000 -p 2222:22 -d gnode/gin-web
You can now visit the website of your GIN server at port 3000 (see the first -p above) of your local machine (localhost:3000).
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.
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:
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).
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:
docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -e GITUID="1001" -e GITGID="1001" -d gnode/gin-web
where GITUID
and GITGID
are followed by the numerical user and group ids respectively.
Update an existing container
To update an existing GIN docker installation you simply need to pull in the changes:
docker pull gnode/gin-web:latest
afterward, you stop the running instance with:
docker stop <containername>
<containername>
can be determined with:
docker ps
After that you can start a new version using the same command that you started the original docker container with, e.g.:
docker run -v /somefolder/:/data -p 3000:3000 -p 2222:22 -d gnode/gin-web
Deploy and run a full server using docker-compose
The setup for a full server requires docker-compose
and is more complex than the simple, local docker
setup.
But it comes with notes on persistent storage, server customization and notes on how to configure the GIN client
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.
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.
This setup will require the files found in the 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.
Required directories
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
- custom frontend files
This schema notes all required directories and files:
$GIN_ROOT_FOLDER
├── config
| ├── postgres
| | └── pgressecrets.env
| └── gogs
| ├── notice
| | └── banner.md # GIN page notice banner
| ├── public # custom frontend style
| └── templates # custom frontend files
├── volumes
| └── ginweb
├── gindata
| ├── gin-postgresdb
| └── gin-repositories
└── gin-dockerfile
├── .env
└── docker-compose.yml
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 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
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 additional custom content changes please see the "Customize the in-house GIN content" section below
note that every time the content of the public
or tempaltes
folder have been changed, the docker container
needs to be restarted before the changes take effect.
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 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
any webform data 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
Apart from changing the main page, as well as header and footer content as described above, most custom pages are hosted
via the Wiki of a specific GIN repository wiki: Service/Info
. By default the service links and expects the following
pages in this particular wiki: Help
, News
, about
, imprint
, contact
, terms of use
and Datenschutz
.
To create and edit these on your GIN instance
- log in with an administrative user
- create a
Service
organisation
- create a
Service/Info
repository
- set this repo to public
- open this 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"
alternatively to adding these pages via the web interface, you can add an ssh public key to your user and git clone
the wiki repository after it has been initialized:
git clone ssh://git@[your domain]:2121/Service/Info.wiki.git
further information about server frontend customization can be found in the official gogs/gogs documentation about custom templates.
GIN client setup
By default the GIN-client, a command line tool to work with GIN,
is set up to work with the GIN server 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.
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
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:
<Location /debug>
Deny from all
</Location>
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,
directly edit the source code and build your own docker container (run from the root of the repository):
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. 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