Installation¶

Being a docker application, GBD WebSuite doesn’t require any installation per se, however, you need to know a couple of things to get it running.

Directories¶

GBD WebSuite requires some directories to be mounted from your host machine to exchange data with the outside world.

one or more “data” directories. This is where you store your configuration and data. The server never writes to these directories, so it’s a good idea to mount them readonly. These directories can be mounted to arbitrary locations in the container (we use /data by default).
the “var” directory where the server stores its own persistent data like caches and session data. It should be mounted to /gws-var in the container.
a temporary directory. Normally, you’d mount it as tmpfs.

Ports¶

GBD WebSuite exposes ports 80 and 443. You can map them to whatever you want during testing, and to real 80/443 in production.

Main configuration¶

GBD WebSuite expects its main configuration in /data/config.json. If you prefer another location and/or format, set the environment variable GWS_CONFIG to the path of your main config.

External hosts¶

If your GBD WebSuite container needs external connections (most likely, to database servers), you’ll need one or more --add-host options in your docker start command.

Entry point¶

GBD WebSuite has a single entry point, a shell script called gws. To start and stop the server, use one of these

gws server start
gws server stop

Putting it all together¶

So, here are options you need to customize in your docker run command:

one or more “data” mounts
a “var” mount
a “tmp” mount
port mappings
configuration path
external hosts

We have a sample script server-sample.sh , which you can customize to your needs:

#!/usr/bin/env bash

#########################################################
#
# This is a sample startup script for the gws-server
# Refer to the docs for the details
#
#########################################################

# gws version
VERSION='2.3'

# server image
IMAGE=gbdconsult/gws-server:${VERSION}

# your container name
CONTAINER=my-gws-container

# (host) path to your config and projects
DATA_DIR=/var/work/data

# (host) path to the server "var" directory
VAR_DIR=/var/work/gws-var

# (container) path to the main configuration
CONFIG_PATH=/data/config.json

# (public) server http port
HTTP_PORT=3333

# server host
HTTP_HOST=0.0.0.0

# external (e.g. database) host IP
EXTERNAL_IP=172.17.0.1

# external (e.g. database) host name (as used in your projects)
EXTERNAL_HOSTNAME=my.db.server


#########################################################

start_server() {
    docker run \
        --name ${CONTAINER} \
        --env GWS_CONFIG=${CONFIG_PATH} \
        --mount type=bind,src=${DATA_DIR},dst=/data,readonly \
        --mount type=bind,src=${VAR_DIR},dst=/gws-var \
        --mount type=tmpfs,dst=/tmp,tmpfs-mode=1777 \
        --publish ${HTTP_HOST}:${HTTP_PORT}:80 \
        --add-host=${EXTERNAL_HOSTNAME}:${EXTERNAL_IP} \
        --detach \
        --log-driver syslog \
        --log-opt tag=GWS \
        gws-server:${IMAGE} \
        gws server start
}

stop_server() {
    docker exec -it ${CONTAINER} gws server stop
    docker kill --signal SIGINT ${CONTAINER}
    docker rm --force ${CONTAINER}
}

case "$1" in
    start)   start_server ;;
    stop)    stop_server  ;;
    restart) stop_server; start_server ;;
esac