|
|
# GG-CE Overview
|
|
|
|
|
|
**GRIN-Global Community Edition** is an evolution of the original GRIN-Global.
|
|
|
|
|
|
GRIN-Global is divided into three main software components: the *database*, the *server* and the *client*.
|
|
|
|
|
|
![server-client](images/server-client.png)
|
|
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
|
|
# 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.
|
|
|
GG-CE is implemented through two main components: the GG-CE-Server and the GG-CE-Web client that provides a **web user interface** through which genebank staff interact with GG-CE.
|
|
|
|
|
|
The GG-CE web user interface `gg-ce-web` represents the most complete GG-CE client application which covers most genebank operations. Other client applications such as mobile apps to support specific processes in the genebank (e.g. recording trait observations), the [Curator Tool](https://www.grin-global.org/download_ct.html), and other applications may also interact with the **server**.
|
|
|
|
|
|
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).
|
|
|
GG-CE components are packaged as **[Docker](https://www.docker.com) images** and designed for container deployment on Windows, Linux and macOS hosts. There is no “installer”, no Windows registry entries, and no pollution of the host system with software dependencies.
|
|
|
|
|
|
![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.
|
|
|
GG-CE-Server and the 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-Web** containers expose only HTTP endpoints:
|
|
|
|
|
|
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`
|
|
|
|
|
|
- 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](https://letsencrypt.org)).
|
|
|
|
|
|
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).
|
|
|
## Docker compose file
|
|
|
|
|
|
Minimal docker-compose file to deploy GG-CE server and web application with labels for Traefik:
|
|
|
|
... | ... | @@ -95,7 +81,7 @@ networks: |
|
|
|
|
|
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 **[MSSQL](https://www.microsoft.com/en-gb/sql-server/sql-server-2019)** database is the prefered database engine for both GRIN-Global and GRIN-Global Community Edition. While GG-CE allows you to use almost any RDBMS, if you want to use the **[Curator Tool](https://www.grin-global.org/download_ct.html)** 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.
|
|
|
|
... | ... | @@ -103,13 +89,13 @@ The GG-CE server will detect a blank database and will automatically initialize |
|
|
|
|
|
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**)
|
|
|
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.
|
|
|
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]
|
|
|
|
... | ... | @@ -118,32 +104,32 @@ CREATE DATABASE ggce COLLATE SQL_Latin1_General_CP1_CI_AS |
|
|
GO
|
|
|
```
|
|
|
|
|
|
Create separate credentials **ggce** for GG-CE to interact with the database:
|
|
|
Create separate credentials `ggce` for GG-CE to interact with the database:
|
|
|
|
|
|
```sql
|
|
|
USE [**master**]
|
|
|
USE [master]
|
|
|
|
|
|
GO
|
|
|
|
|
|
CREATE LOGIN [**ggce**] WITH PASSWORD = 'someRandomPassword';
|
|
|
CREATE LOGIN [ggce] WITH PASSWORD = 'someRandomPassword';
|
|
|
|
|
|
GO
|
|
|
|
|
|
-- Grant owner permissions on ggce-db
|
|
|
|
|
|
USE [**ggce-db**]
|
|
|
USE [ggce-db]
|
|
|
|
|
|
GO
|
|
|
|
|
|
CREATE USER [**ggce**] FOR LOGIN [**ggce**]
|
|
|
CREATE USER [ggce] FOR LOGIN [ggce]
|
|
|
|
|
|
GO
|
|
|
|
|
|
ALTER AUTHORIZATION ON SCHEMA::[db_owner] TO [**ggce**]
|
|
|
ALTER AUTHORIZATION ON SCHEMA::[db_owner] TO [ggce]
|
|
|
|
|
|
GO
|
|
|
|
|
|
ALTER ROLE [db_owner] ADD MEMBER [**ggce**]
|
|
|
ALTER ROLE [db_owner] ADD MEMBER [ggce]
|
|
|
|
|
|
GO
|
|
|
```
|
... | ... | @@ -154,17 +140,17 @@ GG-CE will detect that the database is blank and will automatically create the d |
|
|
|
|
|
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.
|
|
|
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.
|
|
|
*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.
|
|
|
For testing on macOS and Linux you can run [MSSQL Express](https://www.microsoft.com/en-gb/sql-server/sql-server-2019) as a Docker container. A docker volume is where the server will persist data between service restarts.
|
|
|
|
|
|
```bash
|
|
|
# Create a volume for MSSQL data
|
... | ... | @@ -190,11 +176,15 @@ Once connected to the MSSQL console, follow the instructions above to create a b |
|
|
|
|
|
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** |
|
|
|
- `DB_URL`
|
|
|
JDBC connect string to RDBMS engine
|
|
|
Example: `dbc:sqlserver://mssqlserver1:1433;DatabaseName=ggce-db`
|
|
|
- `DB_USERNAME`
|
|
|
RDMBS username with owner permissions on `ggce` database
|
|
|
Example: `ggce`
|
|
|
- `DB_PASSWORD`
|
|
|
Username password
|
|
|
Example: `someRandomPassword`
|
|
|
|
|
|
|
|
|
|
... | ... | @@ -213,22 +203,29 @@ Please check[ https://gitlab.croptrust.org/grin-global/grin-global-server/-/rele |
|
|
The **GG-CE** server container requires a few configuration options. The options
|
|
|
are provided as environment variables. You need to note:
|
|
|
|
|
|
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.
|
|
|
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.
|
|
|
|
|
|
## GG-CE Server configuration options
|
|
|
|
|
|
Please make note of the following GG-CE server configuration options:
|
|
|
|
|
|
| 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. | |
|
|
|
- `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`
|
|
|
This variable informs GG-CE about the port on which it is publicly accessible.
|
|
|
- `DATA_DIR`
|
|
|
The disk volume that will hold files uploaded by users.
|
|
|
A docker volume ensures that the data persists between container restarts.
|
|
|
Example: `-v ggce-server-data:/data/gringlobal`
|
|
|
- `FRONTEND_URL`
|
|
|
The frontend URL of the GG-CE Web service is/will be accessible.
|
|
|
|
|
|
A docker volume ensures that the data persists between container restarts.
|
|
|
|
... | ... | @@ -261,11 +258,10 @@ docker run --rm --name 'ggce-server' \ |
|
|
|
|
|
**Note:** After hitting **Enter** You should immediately seeing log messages on the console. If not, then your command is not valid. Hit `Ctrl + C` and retry.
|
|
|
|
|
|
GG-CE internally listens on port **8080**. The `-p 8081:8080` flag above instructs docker to map the host port **8081** to the internal port 8080 used by GG-CE.
|
|
|
This makes your GG-CE server accessible at http://YOUR_DOCKER_HOST_IP:8081 and cooresponds with variable `HOST_NAMEANDPORT` in the command above.
|
|
|
GG-CE internally listens on port **8080**. The `-p 8081:8080` flag above instructs docker to map the host port **8081** to the internal port 8080 used by GG-CE. This makes your GG-CE server accessible at http://YOUR_DOCKER_HOST_IP:8081 and cooresponds with variable `HOST_NAMEANDPORT` in the command above.
|
|
|
|
|
|
When you see the message `[INFO] Started Jetty Server` you can connect to your own GG-CE instance on the IP of the host
|
|
|
and port **8081** (if you used the command above) at http://YOUR_DOCKER_HOST_IP:8081.
|
|
|
and port **8081** (if you used the command above) at `http://your-docker-host:8081`
|
|
|
|
|
|
|
|
|
### Upgrading to newer version
|
... | ... | @@ -281,15 +277,7 @@ docker run... # as above |
|
|
|
|
|
### Next release
|
|
|
|
|
|
The preview of the next version is available as `dockerhub.croptrust.org/grin-global/grin-global-server:2021.11-edge` and
|
|
|
you should update your copy of the image before **restarting** your container:
|
|
|
|
|
|
```bash
|
|
|
# Preview of the next release
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:2021.11-edge
|
|
|
```
|
|
|
|
|
|
**Note:** You can also just run the current *development* version using the `:edge` tag:
|
|
|
The preview of the next version is available as `dockerhub.croptrust.org/grin-global/grin-global-server:2021.11-edge` and you should update your copy of the image before *restarting* your container:
|
|
|
|
|
|
```bash
|
|
|
# Current development version
|
... | ... | @@ -300,39 +288,42 @@ docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge |
|
|
|
|
|
Once you can connect to your GG-CE Server, navigate to the Admin section and:
|
|
|
|
|
|
1. Load Geography data
|
|
|
1. Load Taxonomy data
|
|
|
1. Load **Geography** data
|
|
|
1. Load **Taxonomy** data
|
|
|
1. Click **Inspect logs** button and wait for `Taxonomy database updated successfully` message.
|
|
|
1. Optionally fetch accession passport data from Genesys
|
|
|
1. Optionally fetch **accession passport data** from Genesys
|
|
|
|
|
|
Consider installing [GG-CE Web](https://gitlab.croptrust.org/grin-global/grin-global-ui).
|
|
|
|
|
|
|
|
|
|
|
|
# GRIN-Global Client
|
|
|
# GG-CE Web Client
|
|
|
|
|
|
The **GRIN-Global Client** is a set of tools for genebank
|
|
|
technicians, curators and managers to interact with the
|
|
|
[GG-CE Server](https://gitlab.croptrust.org/grin-global/grin-global-server) APIs.
|
|
|
The **GRIN-Global Client** is a set of tools for genebank technicians, curators and managers to interact with the[GG-CE Server](https://gitlab.croptrust.org/grin-global/grin-global-server) APIs.
|
|
|
|
|
|
Please check https://gitlab.croptrust.org/grin-global/grin-global-ui/-/releases for
|
|
|
information on new releases!
|
|
|
Please check https://gitlab.croptrust.org/grin-global/grin-global-ui/-/releases for information on new releases!
|
|
|
|
|
|
|
|
|
## Running GG-CE Web
|
|
|
|
|
|
**GG-CE Web** is available as a Docker image `dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.10`.
|
|
|
**GG-CE Web** is available as a Docker image
|
|
|
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:latest
|
|
|
```
|
|
|
|
|
|
It works best with [GG-CE Server](https://gitlab.croptrust.org/grin-global/grin-global-server) image
|
|
|
|
|
|
It works best with [GG-CE Server](https://gitlab.croptrust.org/grin-global/grin-global-server) image `dockerhub.croptrust.org/grin-global/grin-global-server:2021.10`.
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-server:latest
|
|
|
```
|
|
|
|
|
|
The **GG-CE Web** container requires a few configuration options. The options
|
|
|
are provided as environment variables. You need to note:
|
|
|
The **GG-CE Web** container requires a few configuration options. The options are provided as environment variables. You need to note:
|
|
|
|
|
|
1. `API_URL`: The URL to the **GG-CE Server** (e.g. `http://GGCE-SERVER:8081`)
|
|
|
This should match the host name (including port, if not default) where *gg-ce-server* is accessible.
|
|
|
This should match the *host name* (including port, if not default) where *gg-ce-server* is accessible.
|
|
|
1. `ORIGIN`: The frontend URL of the **GG-CE Web** service (e.g. `http://GGCE-WEB:3000`)
|
|
|
This should match the `FRONTEND_URL` variable of your *gg-ce-server* container when using the default OAuth client.
|
|
|
You can omit this if using a OAuth client you declared manually.
|
|
|
This should match the `FRONTEND_URL` variable of your *gg-ce-server* container when using the default OAuth client. You can omit this if using a OAuth client you declared manually.
|
|
|
1. `CLIENT_ID` and `CLIENT_SECRET`: OAuth Client credentials (or skip to use default values)
|
|
|
OAuth client credentials of **gg-ce-web**.
|
|
|
|
... | ... | @@ -344,12 +335,12 @@ docker run --rm --name 'ggce-web' \ |
|
|
-p 3000:3000 \
|
|
|
-e "API_URL=http://GGCE-SERVER:8081" \
|
|
|
-e "ORIGIN=http://GGCE-WEB:3000" \
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.10
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:latest
|
|
|
```
|
|
|
|
|
|
**Note:** After hitting **Enter** You should immediately seeing log messages on the console. If not, then your command is not valid. Hit `Ctrl + C` and retry.
|
|
|
|
|
|
GG-CE Web internally listens on port **3000**. The `-p 3000:3000` flag above instructs docker to map the host port **3000** to the internal container port **3000**. This makes the GG-CE web interface accessible at http://GGCE-WEB:3000.
|
|
|
GG-CE Web internally listens on port **3000**. The `-p 3000:3000` flag above instructs docker to map the host port **3000** to the internal container port **3000**. This makes the GG-CE web interface accessible at `http://GGCE-WEB:3000`
|
|
|
|
|
|
### Troubleshooting
|
|
|
|
... | ... | @@ -385,14 +376,13 @@ Application config { |
|
|
|
|
|
## Next release
|
|
|
|
|
|
The preview of the next release is available as `dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.11-edge` and
|
|
|
you should update your copy of the image before **restarting** your container:
|
|
|
The preview of the next release is available as
|
|
|
|
|
|
```bash
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:2021.11-edge
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:edge
|
|
|
```
|
|
|
|
|
|
**Note:** You can also just run the current *development* version using the `:edge` tag:
|
|
|
You should update your copy of the image before **restarting** your container:
|
|
|
|
|
|
```bash
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:edge
|
... | ... | @@ -406,10 +396,10 @@ docker image pull dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:e |
|
|
|
|
|
Please note that you must configure `grin-global-server` docker container as documented at https://gitlab.croptrust.org/grin-global/grin-global-server#configuration.
|
|
|
|
|
|
1. The name or IP address of the MSSQL server
|
|
|
2. Username and password for the MSSQL
|
|
|
3. The name or IP address where **GG-CE Server** will be accessible
|
|
|
4. The frontend URL of the **GG-CE Web** service will be accessible
|
|
|
1. The *name* or *IP address* of the MSSQL server
|
|
|
2. *Username* and *password* for the MSSQL
|
|
|
3. The *name* or *IP address* where **GG-CE Server** will be accessible
|
|
|
4. The *frontend URL* of the **GG-CE Web** service
|
|
|
|
|
|
#### `docker run`
|
|
|
|
... | ... | |