Deploy GGCE with Docker

Let us guide you through the steps of configuring and deploying GGCE on your infrastructure.

success

Download the sample configuration and adjust it to your needs. The sample is configured to use ggce.local and ggceapi.local names, provides self-signed certificate, and includes the dummy CA Certificate that you can register as a trusted Certificate Authority for testing purposes.

Use the form below to generate customized instructions to set up your GGCE containers. It will create:

A ggce.yml file for use with docker compose
Customized instructions to test and troubleshoot GGCE containers
Database instructions

The data entered here is stored only in your browser.

System name

Give your GGCE a name

Docker host

Domain name (FQDN) or the IP address of the machine hosting your Docker services. This must not be localhost because those names do not resolve they way you would like inside a docker container.

Domain names for GGCE

Two DNS entries are required: one for accessing the GGCE website (frontend) and one for the GGCE server (API). The domain names for need to be registered in your (internal) DNS as CNAME records pointing to the server 10.11.0.1.

info

Please consult your IT Administrator about registering the required DNS entries.

Domain name for GGCE website

Users will access GGCE at https://ggce.local

Domain name for GGCE API

GGCE API will be accessible at https://ggceapi.local

note

For testing on your computer you can add the following names to the hosts file:

127.0.0.1 ggceapi.local ggce.local

Read how to add the names manually to the hosts file on your computer.

HTTPS configuration

Secure https connection from the browser to GGCE ensures that GGCE can provide full functionality to users. Without https, they will not be able to scan barcodes with their camera nor print labels.

You may use IIS on Windows and haproxy/nginx/apache on Linux as a reverse proxy with SSL offloading. Traefik is commonly used when running containerized software.

Traefik

Use Traefik to manage https and http connections

Traefik is an open-source router that receives requests on behalf of your system and finds out which components are responsible for handling them.

Secure HTTP traffic

Use secure https connections with Traefik

Access to camera for barcode scanning only works on localhost or when using https:// protocol. Read Traefik documentation.

Database

Database engine

Database host and port

The DNS name or IP address of the database server and the port. The default value assumes it is running on the Docker host on port 1433.

GGCE database name

The name of the database for GGCE data on the database server.

Database username

The login username to connect to ggce database on host.docker.internal:1433.

Password

The password for database user ggce.

Container options

Memory allocated to GGCE

GGCE requires at least 3G of memory, but the more, the better.

GGCE version

Check for the latest release on GGCE Support page!

Branding

Background color of the menu header

Use yellow or orange color to warn users that they are accesing the test environment.

Brand label

A short, friendly name displayed next to the GGCE logo on all pages.

Your customized GGCE docker configuration

docker compose is a convenient mechanism to configure containers. The configuration files use YAML syntax.

Create a new folder called ggce on your computer.

A common location is C:\ggce on Windows.
Note: Use different folders for your production and test instances.

In this folder create a blank file ggce.yml with the contents as shown below.
Create a subfolder called traefik.
The ggce/traefik folder will contain the reverse proxy configuration and SSL certificates.
Add traefik.yml and dynamic.yml files to the ggce/traefik folder.

ggce.yml
traefik/traefik.yml
traefik/dynamic.yml

version: '3.8'

services:
  ggce-api:
    image: dockerhub.croptrust.org/grin-global/grin-global-server:2024.2
    platform: linux/amd64
    environment:
      # Database connection
      - DB_URL=jdbc:sqlserver://host.docker.internal:1433;DatabaseName=ggce
      - DB_USERNAME=ggce
      - DB_PASSWORD=YourStrong@Passw0rd
      # GGCE URLs
      - BASE_URL=https://ggceapi.local
      - FRONTEND_URL=https://ggce.local
      # Advanced options
      - CACHE_LIBRARY=ehcache
      - JAVA_OPTIONS=-Xlog:gc -XX:+UseG1GC -XX:MinRAMPercentage=50.0 -XX:MaxRAMPercentage=90.0 -Djava.awt.headless=true -server -Dnetworkaddress.cache.ttl=60 -Dcom.sun.security.enableAIAcaIssuers=true --add-modules java.se --add-exports java.base/jdk.internal.ref=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.management/sun.management=ALL-UNNAMED --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED
    volumes:
     - ggce-data:/data/gringlobal
# Enable host.docker.internal on Linux
#     extra_hosts:
#     - "host.docker.internal:host-gateway"
    networks:
      default:
        aliases:
          - ggce-api
      traefik: # Register the container on Traefik network
#    ports:
#      - 8080:8080 # Not exposed, handled by Traefik
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/robots.txt"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 300s
    deploy:
      resources:
        limits:
          memory: 4g
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik"
      - "traefik.http.routers.ggceapi_http.rule=Host(`ggceapi.local`)"
      - "traefik.http.routers.ggceapi_http.entrypoints=http"
      - "traefik.http.middlewares.ggceapi-redirect-http.redirectscheme.scheme=https"
      - "traefik.http.routers.ggceapi.rule=Host(`ggceapi.local`)"
      - "traefik.http.routers.ggceapi.entrypoints=https"
      - "traefik.http.routers.ggceapi.tls=true"


  ggce-ui:
    image: dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2024.2
    platform: linux/amd64
    environment:
      - API_URL=https://ggceapi.local
      - API_URL_INTERNAL=http://ggce-api:8080 # This uses the internal network alias of the API service
      - ORIGIN=https://ggce.local
      - NAME=Genebank Information System
      - NAME_SHORT=Demo
      - MENU_COLOR=#683a29
    networks:
      default:
      traefik: # Register the container on Traefik network
#    ports:
#      - 3000:3000 # Not exposed, handled by Traefik
    depends_on:
      ggce-api:
        condition: service_healthy
    deploy:
      resources:
        limits:
          memory: 400m
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik"
      - "traefik.http.routers.ggceui_http.rule=Host(`ggce.local`)"
      - "traefik.http.routers.ggceui_http.entrypoints=http"
      - "traefik.http.middlewares.ggceui-redirect-http.redirectscheme.scheme=https"
      - "traefik.http.routers.ggceui.rule=Host(`ggce.local`)"
      - "traefik.http.routers.ggceui.entrypoints=https"
      - "traefik.http.routers.ggceui.tls=true"


  reverse-proxy:
    image: traefik:v2.10
    command:
      - --configFile=/opt/traefik/traefik.yml
    ports:
      - "80:80"       # Port for unencrypted HTTP traffic (can be disabled when https works)
      - "443:443"     # Port for encrypted traffic
#      - "8080:8080"  # Traefik's Web console
    networks:
      traefik: # Note the network name here must correspond with container labels "traefik.docker.network=traefik" above
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # So that Traefik can listen to the Docker events
      - ./traefik/:/opt/traefik/ # Place traefik.yml and dynamic.yml into a subfolder called 'traefik'


volumes:
  ggce-data:
    external: true

networks:
  traefik:
    external: true  # Please register a special network for Traefik: docker network create traefik

#
# This goes into traefik/traefik.yml

global:
  checkNewVersion: false
  sendAnonymousUsage: false

debug: true

log:
  level: debug
  # format: json

entryPoints:
  http:
    address: :80
  https:
    address: :443
    tls:

providers:
  providersThrottleDuration: 5s
  docker:
    exposedByDefault: false
  file:
    filename: /opt/traefik/dynamic.yml
    watch: true


accessLog:
  fields:
    defaultMode: keep
    headers:
      defaultMode: keep
      names:
        Authorization: drop
        Content-Type: keep
        Cookie: drop
        Set-Cookie: drop

api:
  insecure: true

#
# This goes into traefik/dynamic.yml

tls:
  stores:
    default: {}
    # Or alternatively:
#    default:
#      defaultCertificate:
#        certFile: /opt/traefik/default.crt
#        keyFile: /opt/traefik/default.key
  options:
    default:
      sniStrict: true
  certificates:
    - certFile: /opt/traefik/ggce-chain.crt
      keyFile: /opt/traefik/ggce.key

On 10.11.0.1 create a docker network for Traefik:

# Create a docker network for Traefik
docker network create traefik

On 10.11.0.1 create a docker volume for GGCE. The volume is used for files that must be persisted even if the container is restarted.

# Create a docker volume for GGCE
docker volume create ggce-data

Start GGCE containers with docker compose:

# In the folder where you keep your ggce.yml file:
docker compose -f ggce.yml up -d


[+] Running 2/2
⠿ Container ggce-api-1  Healthy         90.8s
⠿ Container ggce-ui-1   Started         0.2s

When containers report a Healthy status you can connect to your GGCE.

Your GGCE links

GGCE is accessible at https://ggce.local and the API at https://ggceapi.local.

To stop the containers use docker compose -f ggce.yml down.

Troubleshooting

Always check docker logs if GGCE is not working. In Docker Desktop click on the container name to see the logs. If using command line, then:

# Find the name of GGCE API
docker ps
# Print the logs
docker logs ggce-api

Inspect the logs and identify the problem. The most common is the connection to the database. Check your ggce.yml and update accordingly!

Keep a copy of your configuration

Backups

Make sure to keep a copy of your GGCE configuration in a safe place.