|
|
# Overview
|
|
|
# GG-CE Overview
|
|
|
|
|
|
**GRIN-Global Community Edition** is an evolution of the original GRIN-Global [ASP.Net](https://dotnet.microsoft.com/apps/aspnet) web application running on [IIS](https://www.iis.net) on a Windows Server.
|
|
|
**GRIN-Global Community Edition** is an evolution of the original GRIN-Global.
|
|
|
|
|
|
The application is divided into two main components: the *server* and the *client*.
|
|
|
GRIN-Global is divided into three main software components: the *database*, the *server* and the *client*.
|
|
|
|
|
|
![server-client](images/server-client.png)
|
|
|
|
|
|
The **GG-Server** manages the applicartion business logic and the [database](https://www.microsoft.com/en-gb/sql-server) which stores the application data. It communicates with the **GG-Client** that provides a web user interface to the application. The server implements both a SOAP and JSON API, the first makes it backward compatible with GG, allowing for use of the Curator Tool and other software that uses the SOAP protocol; the second represents the protocol used by the GC-client to communicate with the server.
|
|
|
The server, **GG-CE-Server**, manages the application business logic and the **database** which stores the application data. It communicates with the **GG-CE-Client** that provides a web user interface for the application. The server implements JSON and SOAP API endpoints that provide the business logic in support of genebank operations. The first makes it backward compatible with GRIN-Global, allowing the use of the Curator Tool and other software that uses the SOAP protocol; the second represents the protocol used by the GG-CE-Client to communicate with the server.
|
|
|
|
|
|
Both server and client components are packaged as Docker images and designed for container deployment on Windows, Linux and macos hosts. This makes it easy for IT department to deploy, manage, backup and upgrade individual components automatically. Containers can run on different hosts as long as they are able to communicate on designated ports. Only the HTTPS port is exposed to the outside world.
|
|
|
The original GRIN-Global is an [ASP.Net](https://dotnet.microsoft.com/apps/aspnet) web application running on [IIS](https://www.iis.net) in a Windows Server, while both the GG-CE-Server and GG-CE-Client components are packaged as Docker images and designed for container deployment on Windows, Linux and macOS hosts. This makes it easy for IT departments to deploy, manage, backup and upgrade individual components automatically. Containers can run on different hosts as long as they are able to communicate on designated ports. Only the HTTPS port is exposed to the outside world.
|
|
|
|
|
|
Following, are the installation instructions for the database, server and the client.
|
|
|
## Trying out GG-CE
|
|
|
|
|
|
**GG-CE Test Environment** is available at[ https://demo.ggce.genebanks.org](https://demo.ggce.genebanks.org/)!Reach out to[ https://gitlab.croptrust.org/grin-global/support](https://gitlab.croptrust.org/grin-global/support) for assistance.
|
|
|
|
|
|
|
|
|
# SQL Server
|
|
|
|
|
|
You can use an existing GRIN-Global MSSQL database, or setup and run MSSQL Express service as a Docker container. A docker volume is where the server will persist data between service restarts.
|
|
|
# GG-CE Installation Guide
|
|
|
|
|
|
###### *For IT administrators only*
|
|
|
|
|
|
GG-CE is implemented through two main components: the GG-CE-Server and another service, GG-CE-Client, that provides a **web user interface** which makes it easier for technical staff to operate the application.
|
|
|
|
|
|
Client applications are mobile apps, web applications and the Curator Tool. The GG-CE web user interface **gg-ce-web** represents the most complete GG-CE client application which covers most genebank operations. Mobile apps are usually developed to support specific processes in the genebank (e.g. recording trait observations).
|
|
|
|
|
|
![production-environment](images/production-environment.png)
|
|
|
|
|
|
GG-CE-Server and web application services run as different containers and they must be able to communicate on the designated ports. The server must be able to access the RDBMS.
|
|
|
|
|
|
Both **GG-CE-Server** and **GG-CE-Client** containers expose only HTTP endpoints:
|
|
|
|
|
|
- Server: HTTP on TCP port **8080**
|
|
|
- Web: HTTP on TCP port **3000**
|
|
|
|
|
|
In a Production environment one would commonly use *[Traefik](https://traefik.io)* or an alternative proxy solution to handle incoming connections. In that case the TCP ports do not need to be exposed outside the container environment; *Traefik* is the only service exposed to the Internet. Traefik can automatically manage SSL certificates (e.g. utilizing LetsEncrypt.org).
|
|
|
|
|
|
Minimal docker-compose file to deploy GG-CE server and web application with labels for Traefik:
|
|
|
|
|
|
```yaml
|
|
|
version: '3'
|
|
|
|
|
|
services:
|
|
|
ggce-server:
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-server:2021.8
|
|
|
environment:
|
|
|
# Database connection
|
|
|
- DB_URL=jdbc:sqlserver://35.221.232.153:1433;DatabaseName=gringlobal
|
|
|
- DB_USERNAME=SA
|
|
|
- DB_PASSWORD=*****************
|
|
|
# Host names and URLs
|
|
|
- HOST_NAME=gserver.worldveg.org
|
|
|
- BASE_URL=http://gserver.worldveg.org
|
|
|
- FRONTEND_URL=http://gclient.worldveg.org
|
|
|
restart: always
|
|
|
networks:
|
|
|
- web
|
|
|
logging:
|
|
|
options:
|
|
|
max-size: "100k"
|
|
|
max-file: "3"
|
|
|
labels:
|
|
|
- "traefik.docker.network=web"
|
|
|
- "traefik.enable=true"
|
|
|
- "traefik.basic.frontend.rule=Host:gserver.worldveg.org"
|
|
|
- "traefik.basic.port=8080"
|
|
|
- "traefik.basic.protocol=http"
|
|
|
|
|
|
ggce-ui:
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.8
|
|
|
environment:
|
|
|
- API_URL=http://gserver.worldveg.org
|
|
|
- ORIGIN=http://gclient.worldveg.org
|
|
|
restart: always
|
|
|
networks:
|
|
|
- web
|
|
|
logging:
|
|
|
options:
|
|
|
max-size: "100k"
|
|
|
max-file: "3"
|
|
|
labels:
|
|
|
- "traefik.docker.network=web"
|
|
|
- "traefik.enable=true"
|
|
|
- "traefik.basic.frontend.rule=Host:gclient.worldveg.org"
|
|
|
- "traefik.basic.port=3000"
|
|
|
- "traefik.basic.protocol=http"
|
|
|
networks:
|
|
|
web:
|
|
|
external: true
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
# The Database
|
|
|
|
|
|
An RDBMS needs to be available to GG-CE. You should use an existing database engine provided by your IT department, this ensures that your data is properly managed, secured, and backed up.
|
|
|
|
|
|
The **MSSQL** database is the prefered database engine for GRIN-Global. While GG-CE allows you to use almost any RDBMS, if you want to use the **Curator Tool** with GG-CE, you must use the MSSQL database engine for which up-to-date queries are available. SQL queries for other engines are not actively maintained in the original GG.
|
|
|
|
|
|
The GG-CE server will detect a blank database and will automatically initialize the database schema and populate it with initial data on first startup.
|
|
|
|
|
|
## Configuration notes
|
|
|
|
|
|
The important database options to note are:
|
|
|
|
|
|
1. The hostname (or IP address) and port of the RDBMS engine (e.g. **mssqlserver1**:**1433**)
|
|
|
2. The name of the GG-CE database (e.g. **ggce-db**)
|
|
|
3. Credentials of a user with owner permissions to the GG-CE database.
|
|
|
|
|
|
## **Preparing a new MSSQL database for GG-CE**
|
|
|
|
|
|
Connect to your MSSQL database instance and create a new database **ggce-db**. Please make sure that you use *SQL_Latin1_General_CP1_CI_AS* collation.
|
|
|
|
|
|
[TODO add screenshots from MSSQL Management Studio]
|
|
|
|
|
|
```sql
|
|
|
CREATE DATABASE ggce COLLATE SQL_Latin1_General_CP1_CI_AS
|
|
|
GO
|
|
|
```
|
|
|
|
|
|
Create separate credentials **ggce** for GG-CE to interact with the database:
|
|
|
|
|
|
```sql
|
|
|
USE [**master**]
|
|
|
|
|
|
GO
|
|
|
|
|
|
CREATE LOGIN [**ggce**] WITH PASSWORD = 'someRandomPassword';
|
|
|
|
|
|
GO
|
|
|
|
|
|
-- Grant owner permissions on ggce-db
|
|
|
|
|
|
USE [**ggce-db**]
|
|
|
|
|
|
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
|
|
|
```
|
|
|
|
|
|
GG-CE will detect that the database is blank and will automatically create the database schema and populate it with the initial data, including the default administrator/administrator user account.
|
|
|
|
|
|
## Using an existing GRIN-Global database
|
|
|
|
|
|
GG-CE is backwards compatible with the original GRIN-Global databases. You can upgrade your existing GG database and use it with GG-CE.
|
|
|
|
|
|
1. Make a backup of your existing GG database.
|
|
|
2. Restore the backup as a new database.
|
|
|
3. Configure GG-CE server to use the restored database.
|
|
|
4. GG-CE will upgrade the database model to add support for GG-CE functionality.
|
|
|
5. You cannot run both GG and GG-CE against the same database.
|
|
|
|
|
|
Note: The GRIN-Global user credentials remain the same, make sure you have one GG user in the “ADMINS” group.
|
|
|
|
|
|
## Running MSSQL as a Docker container
|
|
|
|
|
|
You can use an existing GRIN-Global MSSQL database, or setup and run MSSQL Express service as a Docker container. A docker volume is where the server will persist data between service restarts.
|
|
|
|
|
|
```bash
|
|
|
# Create a volume for MSSQL data
|
... | ... | @@ -37,57 +184,58 @@ docker exec -it mssql-ggce \ |
|
|
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStrong@Passw0rd'
|
|
|
```
|
|
|
|
|
|
Create a **blank** `ggce` database with `SQL_Latin1_General_CP1_CI_AS` collation
|
|
|
(case-insensitive, accent-sensitive):
|
|
|
Once connected to the MSSQL console, follow the instructions above to create a blank database for GG-CE.
|
|
|
|
|
|
```sql
|
|
|
CREATE DATABASE ggce COLLATE SQL_Latin1_General_CP1_CI_AS
|
|
|
GO
|
|
|
```
|
|
|
## GG-CE database configuration options
|
|
|
|
|
|
Please make note of the following database configuration options:
|
|
|
|
|
|
| Variable | Description | Example |
|
|
|
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------ |
|
|
|
| DB_URL | JDBC connect string to RDBMS engine | dbc:sqlserver://**mssqlserver1**:**1433**;DatabaseName=**ggce-db** |
|
|
|
| DB_USERNAME | RDMBS username with owner permissions on **ggce** database | **ggce** |
|
|
|
| DB_PASSWORD | The password | **someRandomPassword** |
|
|
|
|
|
|
# GG-CE Server
|
|
|
|
|
|
This is a Java implementation of the GRIN-Global middle-tier.
|
|
|
The APIs provided by this implementation are mostly compatible with
|
|
|
the original implementation of the .Net GRIN-Global.Server.
|
|
|
|
|
|
Please check https://gitlab.croptrust.org/grin-global/grin-global-server/-/releases for
|
|
|
information on new releases!
|
|
|
# GG-CE Server
|
|
|
|
|
|
## Trying out GG-CE
|
|
|
**GG-CE Server** is available as a Docker image
|
|
|
|
|
|
**GG-CE Test Environment** is available at https://demo.ggce.genebanks.org!
|
|
|
Reach out to https://gitlab.croptrust.org/grin-global/support for assistance.
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-server:latest
|
|
|
```
|
|
|
|
|
|
## Running the server
|
|
|
Please check[ https://gitlab.croptrust.org/grin-global/grin-global-server/-/releases](https://gitlab.croptrust.org/grin-global/grin-global-server/-/releases) for information on new releases!
|
|
|
|
|
|
**GG-CE Server** is available as a Docker image `dockerhub.croptrust.org/grin-global/grin-global-server:2021.10`.
|
|
|
This allows for easy management and updating to newer versions.
|
|
|
## Configuration notes
|
|
|
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-server:2021.10
|
|
|
```
|
|
|
The **GG-CE** server container requires a few configuration options. The options
|
|
|
are provided as environment variables. You need to note:
|
|
|
|
|
|
The **MSSQL** database is the prefered database engine for GRIN-Global.
|
|
|
If you run the server using any other database engine, there are no
|
|
|
guarantees that the **Curator Tool** will work.
|
|
|
1. The database configuration options.
|
|
|
1. The disk volume that will hold files uploaded by users.
|
|
|
1. The name and the TCP port where **GG-CE Server** will be accessible.
|
|
|
1. Optionally: The frontend URL of the **GG-CE Web** service will be accessible.
|
|
|
|
|
|
The server will initialize the database schema and populate it with initial
|
|
|
data automatically. Alternatively, upgrade your existing GRIN-Global Database using the standard
|
|
|
installer and then configure **GG-CE** to use the MSSQL database.
|
|
|
## GG-CE Server configuration options
|
|
|
|
|
|
Please make note of the following GG-CE server configuration options:
|
|
|
|
|
|
### Configuration
|
|
|
| Variable | Description | Notes |
|
|
|
| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
|
|
| port | The exposed TCP port of GG-CE Server | With docker, the internal GG-CE port 8080 is exposed using the -p flag.For example “-p 80:8080” exposes the internal port 8080 on port 80 of the docker host. |
|
|
|
| HOST_NAME | The DNS name where the GG-CE server will be accessible to clients. | Used to set HTTP cookie domain. Must not include port number. |
|
|
|
| HOST_NAMEANDPORT | | The -p flag (above) is a docker container flag. This variable informs GG-CE about the port on which it is publicly accessible.Use “hostname:port” syntax. [*Milko - not clear*] |
|
|
|
| DATA_DIR | The disk volume that will hold files uploaded by users. | A docker volume ensures that the data persists between container restarts.<br />-v ggce-server-data:/data/gringlobal |
|
|
|
| FRONTEND_URL | The frontend URL of the GG-CE Web service is/will be accessible. | |
|
|
|
|
|
|
The **GG-CE** server container requires a few configuration options. The options
|
|
|
are provided as environment variables. You need to note:
|
|
|
A docker volume ensures that the data persists between container restarts.
|
|
|
|
|
|
1. The name or IP address of the MSSQL server
|
|
|
1. Username and password for the MSSQL
|
|
|
1. The name or IP address where **GG-CE Server** will be accessible, commonly the name or IP of your Docker host (e.g. `192.168.99.105`)
|
|
|
1. The frontend URL of the **GG-CE Web** service will be accessible, commonly the name or IP of your Docker host (e.g. `http://192.168.99.105:3000`)
|
|
|
```bash
|
|
|
# Create a data volume
|
|
|
docker volume create ggce-server-data
|
|
|
```
|
|
|
|
|
|
Start **GG-CE Server** as a Docker container:
|
|
|
|
... | ... | @@ -95,9 +243,6 @@ Start **GG-CE Server** as a Docker container: |
|
|
# Pull latest image
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:2021.10
|
|
|
|
|
|
# Create a data volume
|
|
|
docker volume create ggce-server-data
|
|
|
|
|
|
# Start GRIN-Global Server
|
|
|
# Make sure that address for MSSQL "jdbc:sqlserver://172.17.0.2:1433" is
|
|
|
# equal to ip from `docker inspect mssql-ggce` output
|
... | ... | @@ -151,7 +296,7 @@ docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:2021.11 |
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge
|
|
|
```
|
|
|
|
|
|
## Populating the database
|
|
|
## First Start
|
|
|
|
|
|
Once you can connect to your GG-CE Server, navigate to the Admin section and:
|
|
|
|
... | ... | @@ -162,10 +307,6 @@ Once you can connect to your GG-CE Server, navigate to the Admin section and: |
|
|
|
|
|
Consider installing [GG-CE Web](https://gitlab.croptrust.org/grin-global/grin-global-ui).
|
|
|
|
|
|
## Migrating from GRIN-Global
|
|
|
|
|
|
TBD
|
|
|
|
|
|
|
|
|
|
|
|
# GRIN-Global Client
|
... | ... | @@ -177,11 +318,6 @@ technicians, curators and managers to interact with the |
|
|
Please check https://gitlab.croptrust.org/grin-global/grin-global-ui/-/releases for
|
|
|
information on new releases!
|
|
|
|
|
|
## Trying out GG-CE
|
|
|
|
|
|
**GG-CE Test Environment** is available at https://demo.ggce.genebanks.org!
|
|
|
Reach out to https://gitlab.croptrust.org/grin-global/support for assistance.
|
|
|
|
|
|
|
|
|
## Running GG-CE Web
|
|
|
|
... | ... | @@ -266,12 +402,6 @@ docker image pull dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:e |
|
|
|
|
|
# GG-CE Deployment
|
|
|
|
|
|
GG-CE is packaged as Docker images and designed for container deployment on Windows, Linux and macos hosts. This makes it easy for IT department to deploy, manage, backup and upgrade individual components automatically.
|
|
|
|
|
|
![production-environment](images/production-environment.png)
|
|
|
|
|
|
Containers can run on different hosts as long as they are able to communicate on designated ports. Only the HTTPS port is exposed to the outside world.
|
|
|
|
|
|
## Use Traefik to run the containers
|
|
|
|
|
|
Please note that you must configure `grin-global-server` docker container as documented at https://gitlab.croptrust.org/grin-global/grin-global-server#configuration.
|
... | ... | @@ -348,56 +478,3 @@ db.password=sa1 |
|
|
|
|
|
Any of the properties can be configured using **environment** variables. Please convert the property name to uppercase and replace **.** with **_**: `db.url` becomes `DB_URL`.
|
|
|
|
|
|
### Sample compose file
|
|
|
|
|
|
```yaml
|
|
|
version: '3'
|
|
|
|
|
|
services:
|
|
|
ggce-server:
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-server:2021.8
|
|
|
environment:
|
|
|
# Database connection
|
|
|
- DB_URL=jdbc:sqlserver://35.221.232.153:1433;DatabaseName=gringlobal
|
|
|
- DB_USERNAME=SA
|
|
|
- DB_PASSWORD=*****************
|
|
|
# Host names and URLs
|
|
|
- HOST_NAME=gserver.worldveg.org
|
|
|
- BASE_URL=http://gserver.worldveg.org
|
|
|
- FRONTEND_URL=http://gclient.worldveg.org
|
|
|
restart: always
|
|
|
networks:
|
|
|
- web
|
|
|
logging:
|
|
|
options:
|
|
|
max-size: "100k"
|
|
|
max-file: "3"
|
|
|
labels:
|
|
|
- "traefik.docker.network=web"
|
|
|
- "traefik.enable=true"
|
|
|
- "traefik.basic.frontend.rule=Host:gserver.worldveg.org"
|
|
|
- "traefik.basic.port=8080"
|
|
|
- "traefik.basic.protocol=http"
|
|
|
|
|
|
ggce-ui:
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.8
|
|
|
environment:
|
|
|
- API_URL=http://gserver.worldveg.org
|
|
|
- ORIGIN=http://gclient.worldveg.org
|
|
|
restart: always
|
|
|
networks:
|
|
|
- web
|
|
|
logging:
|
|
|
options:
|
|
|
max-size: "100k"
|
|
|
max-file: "3"
|
|
|
labels:
|
|
|
- "traefik.docker.network=web"
|
|
|
- "traefik.enable=true"
|
|
|
- "traefik.basic.frontend.rule=Host:gclient.worldveg.org"
|
|
|
- "traefik.basic.port=3000"
|
|
|
- "traefik.basic.protocol=http"
|
|
|
networks:
|
|
|
web:
|
|
|
external: true
|
|
|
``` |