|
|
|
|
|
# Install GG-CE in three simple steps
|
|
|
# Install GGCE in three simple steps
|
|
|
|
|
|
1. Set up a MSSQL database.
|
|
|
2. Designate a volume for GG-CE file repository.
|
|
|
3. Update the Docker compose file and start up your instance of GG-CE.
|
|
|
2. Designate a volume for GGCE file repository.
|
|
|
3. Update the Docker compose file and start up your instance of GGCE.
|
|
|
|
|
|
**NOTE: This guide is work-in-progress!** Contact [GGCE Support](mailto:gitlab+grin-global-support-178-issue-@croptrust.org) for assistance!
|
|
|
|
|
|
# **NOTE: This guide is work-in-progress!**
|
|
|
# GGCE Installation Guide
|
|
|
|
|
|
# GG-CE Installation Guide
|
|
|
**GGCE** is implemented through two main components: the GGCE-Server and the grin-global-web client that provides a **web user interface** through which genebank staff interact with GGCE.
|
|
|
|
|
|
**GRIN-Global Community Edition** (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 **GGCE-Server** manages the application business logic, interacts with the **database** which stores the application data, and with a **file volume** to store user-uploaded files and documents.
|
|
|
|
|
|
The **GG-CE-Server** manages the application business logic, interacts with the **database** which stores the application data, and with a **file volume** to store user-uploaded files and documents.
|
|
|
The GGCE web user interface **grin-global-web** represents the most complete GGCE client application and 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, and other applications may also interact with the GGCE JSON or SOAP API provided by the **server**.
|
|
|
|
|
|
The GG-CE web user interface **gg-ce-web** represents the most complete GG-CE client application and 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, and other applications may also interact with the GG-CE JSON or SOAP API provided by the **server**.
|
|
|
|
|
|
GG-CE components are packaged as **Docker images** and designed for container deployment on Windows, Linux and macOS hosts.
|
|
|
GGCE components are packaged as **Docker images** and designed for container deployment on Windows, Linux and macOS hosts.
|
|
|
|
|
|
![production-environment](images/production-environment.png)
|
|
|
|
|
|
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.
|
|
|
The GGCE 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 **GGCE Server** and **GGCE Web** containers expose only HTTP endpoints:
|
|
|
|
|
|
- Server: HTTP on TCP port `8080`
|
|
|
- Web: HTTP on TCP port `3000`
|
... | ... | @@ -31,7 +30,7 @@ In a Production environment one would commonly use *[Traefik](https://traefik.io |
|
|
|
|
|
## Docker compose file
|
|
|
|
|
|
Minimal docker-compose file to deploy GG-CE server and web application with labels for Traefik:
|
|
|
Minimal docker-compose file to deploy GGCE server and web application with labels for Traefik:
|
|
|
|
|
|
```yaml
|
|
|
version: '3'
|
... | ... | @@ -89,21 +88,21 @@ networks: |
|
|
|
|
|
# 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.
|
|
|
An RDBMS needs to be available to GGCE. You should use an existing database engine provided by your IT department, this ensures that your data is properly managed, secured, and backed up.
|
|
|
|
|
|
MSSQL Server is the prefered database engine for both GRIN-Global and GG-CE. 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.
|
|
|
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 **[Curator Tool](https://www.grin-global.org/download_ct.html)** with GGCE, you must use the MSSQL database engine for which up-to-date queries are available. SQL queries for other engines are not actively maintained.
|
|
|
|
|
|
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.
|
|
|
The GGCE 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.
|
|
|
2. The name of the GGCE database (e.g. `ggce-db`)
|
|
|
3. Credentials of a user with owner permissions to the GGCE database.
|
|
|
|
|
|
## **Preparing a new MSSQL database for GG-CE**
|
|
|
## **Preparing a new MSSQL database for GGCE**
|
|
|
|
|
|
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.
|
|
|
|
... | ... | @@ -114,7 +113,7 @@ 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 GGCE to interact with the database:
|
|
|
|
|
|
```sql
|
|
|
USE [master]
|
... | ... | @@ -133,17 +132,17 @@ ALTER ROLE [db_owner] ADD MEMBER [ggce] |
|
|
GO
|
|
|
```
|
|
|
|
|
|
At startup GG-CE will detect if 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.
|
|
|
At startup GGCE will detect if 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.
|
|
|
GGCE is backwards compatible with the original GRIN-Global databases. You can upgrade your existing GG database and use it with GGCE.
|
|
|
|
|
|
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*.
|
|
|
3. *Configure* GGCE server to *use the restored database*.
|
|
|
4. GGCE *will upgrade the database model* to add support for GGCE functionality.
|
|
|
5. *You cannot run both GG and GGCE against the same database*.
|
|
|
|
|
|
*Note*: The GRIN-Global user credentials remain the same, make sure you have one GG user in the “ADMINS” group.
|
|
|
|
... | ... | @@ -171,9 +170,9 @@ docker exec -it mssql-ggce \ |
|
|
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStrong@Passw0rd'
|
|
|
```
|
|
|
|
|
|
Once connected to the MSSQL console, follow the instructions above to create a blank database for GG-CE.
|
|
|
Once connected to the MSSQL console, follow the instructions above to create a blank database for GGCE.
|
|
|
|
|
|
## GG-CE database configuration options
|
|
|
## GGCE database configuration options
|
|
|
|
|
|
Please make note of the following database configuration options:
|
|
|
|
... | ... | @@ -189,9 +188,9 @@ Please make note of the following database configuration options: |
|
|
|
|
|
|
|
|
|
|
|
# GG-CE Server
|
|
|
# GGCE Server
|
|
|
|
|
|
**GG-CE Server** is available as a Docker image
|
|
|
**GGCE Server** is available as a Docker image
|
|
|
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-server:latest
|
... | ... | @@ -201,32 +200,32 @@ Please check[ https://gitlab.croptrust.org/grin-global/grin-global-server/-/rele |
|
|
|
|
|
## Configuration notes
|
|
|
|
|
|
The **GG-CE** server container requires a few configuration options. The options
|
|
|
The **GGCE** 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.
|
|
|
1. The *name* and the *TCP port* where **GGCE Server** will be accessible.
|
|
|
1. Optionally: The *frontend URL* of the **GGCE Web** service.
|
|
|
|
|
|
## GG-CE Server configuration options
|
|
|
## GGCE Server configuration options
|
|
|
|
|
|
Please make note of the following GG-CE server configuration options:
|
|
|
Please make note of the following GGCE server configuration options:
|
|
|
|
|
|
- `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.
|
|
|
The exposed TCP port of GGCE Server
|
|
|
With docker, the internal GGCE 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.
|
|
|
The DNS name where the GGCE 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.
|
|
|
This variable informs GGCE 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.
|
|
|
The frontend URL of the GGCE Web service is/will be accessible.
|
|
|
|
|
|
A **docker volume** ensures that the data persists between container restarts.
|
|
|
|
... | ... | @@ -235,7 +234,7 @@ A **docker volume** ensures that the data persists between container restarts. |
|
|
docker volume create ggce-server-data
|
|
|
```
|
|
|
|
|
|
Start **GG-CE Server** as a Docker container:
|
|
|
Start **GGCE Server** as a Docker container:
|
|
|
|
|
|
```bash
|
|
|
# Pull latest image
|
... | ... | @@ -259,9 +258,9 @@ 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.
|
|
|
GGCE 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 GGCE. This makes your GGCE 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
|
|
|
When you see the message `[INFO] Started Jetty Server` you can connect to your own GGCE instance on the IP of the host
|
|
|
and port **8081** (if you used the command above) at `http://your-docker-host:8081`
|
|
|
|
|
|
|
... | ... | @@ -277,57 +276,57 @@ docker run... # as above |
|
|
```
|
|
|
|
|
|
|
|
|
# GG-CE Web Client
|
|
|
# GGCE 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[GGCE 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!
|
|
|
|
|
|
|
|
|
## Running GG-CE Web
|
|
|
## Running GGCE Web
|
|
|
|
|
|
**GG-CE Web** is available as a Docker image `dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:latest`. It works best with the latest GG-CE Server image `dockerhub.croptrust.org/grin-global/grin-global-server:latest`.
|
|
|
**GGCE Web** is available as a Docker image `dockerhub.croptrust.org/grin-global/grin-global-ui/grin-global-web:latest`. It works best with the latest GGCE Server image `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 **GGCE 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.
|
|
|
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.
|
|
|
1. `API_URL`: The URL to the **GGCE Server** (e.g. `http://GGCE-SERVER:8081`)
|
|
|
This should match the *host name* (including port, if not default) where *GGCE-server* is accessible.
|
|
|
1. `ORIGIN`: The frontend URL of the **GGCE Web** service (e.g. `http://grin-global-web:3000`)
|
|
|
This should match the `FRONTEND_URL` variable of your *GGCE-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**.
|
|
|
OAuth client credentials of **grin-global-web**.
|
|
|
|
|
|
Start **GG-CE Server** as a Docker container:
|
|
|
Start **GGCE Server** as a Docker container:
|
|
|
|
|
|
```bash
|
|
|
# Start GG-CE Web
|
|
|
docker run --rm --name 'ggce-web' \
|
|
|
# Start GGCE Web
|
|
|
docker run --rm --name 'grin-global-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:latest
|
|
|
-e "ORIGIN=http://grin-global-web:3000" \
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-ui/grin-global-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`
|
|
|
GGCE 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 GGCE web interface accessible at `http://grin-global-web:3000`
|
|
|
|
|
|
### Troubleshooting
|
|
|
|
|
|
The effecive configuration is printed out immediately when you start the **gg-ce-web** container.
|
|
|
The effecive configuration is printed out immediately when you start the **grin-global-web** container.
|
|
|
|
|
|
The *Application config* section (example below) displays the values in use. These need to be properly
|
|
|
configured with Docker environment variables.
|
|
|
|
|
|
```bash
|
|
|
Running Genesys UI from /var/www/gg-ce with CLIENT_ID= and API at
|
|
|
Running Genesys UI from /var/www/GGCE with CLIENT_ID= and API at
|
|
|
Starting on TCP port (default 3000).
|
|
|
2020-07-15T15:29:04: PM2 log: Launching in no daemon mode
|
|
|
2020-07-15T15:29:04: PM2 log: App [gg-ce:0] starting in -cluster mode-
|
|
|
2020-07-15T15:29:04: PM2 log: App [gg-ce:0] online
|
|
|
2020-07-15T15:29:04: PM2 log: App [GGCE:0] starting in -cluster mode-
|
|
|
2020-07-15T15:29:04: PM2 log: App [GGCE:0] online
|
|
|
{
|
|
|
_: [ 'start', 'gg-ce.yml' ],
|
|
|
_: [ 'start', 'GGCE.yml' ],
|
|
|
'origin': '',
|
|
|
'api-timeout': '',
|
|
|
'api-url': '',
|
... | ... | @@ -347,16 +346,16 @@ Application config { |
|
|
|
|
|
## Next release
|
|
|
|
|
|
The preview of the next release is available as `dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:edge`.
|
|
|
The preview of the next release is available as `dockerhub.croptrust.org/grin-global/grin-global-ui/grin-global-web:edge`.
|
|
|
|
|
|
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
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-ui/grin-global-web:edge
|
|
|
```
|
|
|
|
|
|
|
|
|
# GG-CE Deployment
|
|
|
# GGCE Deployment
|
|
|
|
|
|
## Use Traefik to run the containers
|
|
|
|
... | ... | @@ -364,8 +363,8 @@ Please note that you must configure `grin-global-server` docker container as doc |
|
|
|
|
|
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
|
|
|
3. The *name* or *IP address* where **GGCE Server** will be accessible
|
|
|
4. The *frontend URL* of the **GGCE Web** service
|
|
|
|
|
|
#### `docker run`
|
|
|
|
... | ... | @@ -408,11 +407,11 @@ Your Traefik labels are OK. |
|
|
- BASE_COOKIESECURE=true
|
|
|
```
|
|
|
|
|
|
Relevant `gg-ce-web` configuration is documented at https://gitlab.croptrust.org/grin-global/grin-global-ui#running-gg-ce-web:
|
|
|
Relevant `gg-ce-web` configuration is documented at https://gitlab.croptrust.org/grin-global/grin-global-ui#running-grin-global-web:
|
|
|
|
|
|
```yaml
|
|
|
ggce-ui:
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:latest
|
|
|
image: dockerhub.croptrust.org/grin-global/grin-global-ui/grin-global-web:latest
|
|
|
environment:
|
|
|
- API_URL=http://ggceserver.mydomain
|
|
|
- ORIGIN=http://ggceweb.mydomain
|
... | ... | @@ -421,7 +420,7 @@ Relevant `gg-ce-web` configuration is documented at https://gitlab.croptrust.org |
|
|
|
|
|
### All system options
|
|
|
|
|
|
**GG-CE** accepts a number of system configuration options. The full list and their default values are listed in [application.properties](https://gitlab.croptrust.org/grin-global/grin-global-server/-/blob/main/server/src/main/resources/application.properties).
|
|
|
**GGCE** accepts a number of system configuration options. The full list and their default values are listed in [application.properties](https://gitlab.croptrust.org/grin-global/grin-global-server/-/blob/main/server/src/main/resources/application.properties).
|
|
|
|
|
|
For example, the default database connection parameters are:
|
|
|
|
... | ... | |