Installation guide

GGCE requires the docker engine and a database server. They can be hosted on the same or on different machines.

The minimum server requirements for running GGCE are:

Requirement	Minimum	Notes
Memory	16GB	A single GGCE instance needs at least 4GB, but 8GB is better. The database engine needs additional 4-8GB
Processor	Any modern CPU with 2+ cores	Each docker container can be limited to use less cores than available.
Disk space	500GB	Extra space might be required for database backup and for files uploaded to GGCE
OS	Linux, Windows, MacOS
Software	Docker engine installed	You can use IIS on Windows and nginx or apache on Linux instead of Traefik as a reverse proxy.

Docker engine

Wikipedia explains Docker as "a tool that is used to automate the deployment of applications in lightweight containers so that applications can work efficiently in different environments in isolation. Docker can package an application and its dependencies in a virtual container that can run on any Linux, Windows, or macOS computer."

GGCE uses containers because this approach allows for simplified management and operation of GGCE services.

Consult with your IT department about GGCE deployment in your organization:

1. Install docker engine on your server.
2. MSSQL Server is the prefered database engine for both GRIN-Global and GGCE.
   • Use the existing central MSSQL server if one is provided by your organization!
   • On Windows you may choose to run MSSQL directly on the server. You will need to enable TCP/IP connections (disabled by default).
   • Or run mssql as a container on any system.
   • Or use MariaDB or Postgres.
3. Prepare a database for GGCE.
4. Deploy GGCE with Docker.
   • On Windows you can use Internet Information Services (IIS) instead of Traefik.
   • On Linux you might want to use your existing nginx or Apache setup instead of Traefik.

WSL2

If you are installing docker on Windows (with or without Docker Desktop) you must use WSL 2. Read more...

After the installation, follow the first steps guide and then review the server configuration options.

Database server

MSSQL Server is the prefered database engine for both GRIN-Global and GGCE. While GGCE allows you to use almost any RDBMS, if you want to use the GRIN-Global Curator Tool and the standard GG Dataviews with GGCE, then you must use the MSSQL database engine for which up-to-date queries are available. SQL queries for other engines are not actively maintained.

MSSQL 2016+

MSSQL server engine must be version 2016 or later! You can check the version of your MSSQL by executing the query: SELECT @@VERSION.

Running MSSQL with Docker

You can run MSSQL as a Docker container on Linux and macOS. On Windows, you can install MSSQL directly.

First, create a docker volume for MSSQL data so that it is persisted between container restarts:

docker volume create mssql-data

Then create:

1. A folder called mssql
2. Inside the mssql folder create a subfolder backups
3. Inside the mssql folder create the mssql-compose.yml file:

mssql-compose.yml

version: '3.8'

services:
  server:
    image: mcr.microsoft.com/mssql/server:2019-latest
    platform: linux/amd64
    container_name: mssql-server
    environment:
      # Use root/example as user/password credentials
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong@Passw0rd
      - MSSQL_PID=Express
      - TZ=UTC
      - MSSQL_COLLATION=SQL_Latin1_General_CP1_CI_AS
      #- MSSQL_LCID=
      # - MSSQL_MEMORY_LIMIT_MB
    volumes:
      - mssql-data:/var/opt/mssql
      - ./backup:/backup # Map a local folder to /backup inside container
    ports:
      - 1433:1433
    deploy:
      resources:
        limits:
          memory: 4g
        # reservations:
        #   memory: 2g
    restart: unless-stopped

volumes:
  mssql-data:
    external: true

Start MSSQL container with docker compose -f mssql-compose.yml up -d.

# Find the name of docker container
docker ps

# Connect to the database engine in Docker
docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStrong@Passw0rd'

Your MSSQL server is also accessible on the standard TCP port 1433 and you can use Microsoft's Azure Data Studio or SQL Server Management Studio (SSMS) to interact with the server.

GGCE database

GGCE is backwards compatible with the original GRIN-Global databases. You can upgrade your existing GG database and use it with GGCE, or if starting from scratch you will create a blank database for GGCE.

Using an existing GRIN-Global database

1. Make a full backup of your existing GG database.
2. Restore the backup as a new database.
3. Set up database credentials for GGCE.
4. Configure GGCE server to use the restored database.
5. GGCE will upgrade the database schema to add support for GGCE functionality.
6. You cannot run both GG and GGCE against the same database.

note

The GRIN-Global usernames and passwords remain unchanged if you restored from an earlier backup.

Starting with a blank database

Create a new database for GGCE and note the collation SQL_Latin1_General_CP1_CI_AS:

USE [master]
GO
CREATE DATABASE [ggce] COLLATE SQL_Latin1_General_CP1_CI_AS
GO

GGCE server will detect a blank database and will automatically populate it with initial data on startup.

Database credentials

Create a separate database login ggce for GGCE to interact with the database:

USE [master]
GO
CREATE LOGIN [ggce] WITH PASSWORD = 'YourStrong@Passw0rd';
GO

-- Grant owner permissions on ggce database
USE [ggce]
GO
CREATE USER [ggce] FOR LOGIN [ggce]
GO
ALTER AUTHORIZATION ON SCHEMA::[db_owner] TO [ggce]
GO
ALTER ROLE [db_owner] ADD MEMBER [ggce]
GO

note

GGCE requires sufficient permissions on ggce database to make changes to the schema.

The system is now ready for GGCE.