GGCE Server

Please visit https://gitlab.croptrust.org/grin-global/support for assistance.

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!

Running the server

GGCE Server is available as a Docker image dockerhub.croptrust.org/grin-global/grin-global-server:latest. This allows for easy management and updating to newer versions.

dockerhub.croptrust.org/grin-global/grin-global-server:latest

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.

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 GGCE to use the MSSQL database.

Configuration

The GGCE server container requires a few configuration options. The options are provided as environment variables. You need to note:

1. The name or IP address of the MSSQL server
2. Username and password for the MSSQL
3. The URL address where GGCE Server will be accessible to users, commonly the URL with the name or IP of your Docker host (e.g. http://192.168.99.105:8081)
4. The frontend URL of the GGCE Web service will be accessible, commonly the name or IP of your Docker host (e.g. http://192.168.99.105:3000)

Start GGCE Server as a Docker container:

# Pull latest image
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:latest

# 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
#
# Windows: Remove the \ from the command below when using cmd.exe!
docker run --rm --name 'ggce-server' \
 -p 8081:8080 \
 -e "DB_URL=jdbc:sqlserver://<MSSQL>:1433;DatabaseName=ggce" \
 -e "DB_USERNAME=sa" \
 -e "DB_PASSWORD=YourStrong@Passw0rd" \
 -e "BASE_URL=http://${YOUR_DOCKER_HOST_IP}:8081" \
 -e "FRONTEND_URL=http://${YOUR_DOCKER_HOST_IP}:3000" \
 -e "DATA_DIR=/data/gringlobal" \
 -v ggce-server-data:/data/gringlobal \
 dockerhub.croptrust.org/grin-global/grin-global-server: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.

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 corresponds with variable HOST_NAMEANDPORT in the command above.

GGCE Server listens on / context path by default. To run it on a /gg-ce virtual path you need to provide the CONTEXT_PATH environment variable to the container and also update the BASE_URL to include the context path:

docker run [...] -e 'CONTEXT_PATH=/gg-ce' -e 'BASE_URL=http://YOUR_DOCKER_HOST_IP:8081/gg-ce' [...]

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 the BASE_URL (http://YOUR_DOCKER_HOST_IP:8081.

Upgrading to newer version

To get the latest version of the image you need to pull the latest image and recreate your container:

docker pull dockerhub.croptrust.org/grin-global/grin-global-server:latest
docker stop ggce-server
docker remove ggce-server # if the container name is still defined
docker run... # as above

Next release

The preview of the next version is available as dockerhub.croptrust.org/grin-global/grin-global-server:edge and you should update your copy of the image before restarting your container:

# Preview of the latest development release
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge

Populating the database

Once you can connect to your GGCE Server, navigate to the Admin section and:

1. Load Geography data
2. Load Taxonomy data
3. Click Inspect logs button and wait for Taxonomy database updated successfully message.
4. Optionally fetch accession passport data from Genesys

Consider installing GGCE Web.

Database setup with Docker

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.

# Create a volume for MSSQL data
docker volume create mssql-ggce-data

# Start MSSQL Express
docker run --name 'mssql-ggce' \
 -e 'ACCEPT_EULA=Y' \
 -e 'SA_PASSWORD=YourStrong@Passw0rd' \
 -e 'MSSQL_PID=Express' \
 -e 'TZ=UTC' \
 -v mssql-ggce-data:/var/opt/mssql \
 mcr.microsoft.com/mssql/server:2019-latest

# Connect to the database engine
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):

CREATE DATABASE ggce COLLATE SQL_Latin1_General_CP1_CI_AS
GO

For developers

Most IDEs will resolve project modules automatically. From the command line, you may want to start with

# Build and locally install current modules
mvn install

Then cd server to the server module.

Copy the myconfig.properties.example to myconfig.properties in the project folder. Update the configuration options to connect to your MSSQL gringlobal database:

db.url=jdbc:sqlserver://localhost:1433;DatabaseName=gringlobal
db.username=sa
db.password=sa1

Start the embedded web server from the terminal:

# Switch to server module
cd server/
mvn -DskipTests=true jetty:run

Start the Curator Tool. Add a new GRIN-Global server with display name java and server name (or IP Address) localhost:8080.

Skip "Test Server Address".

Connect to the java server and enjoy the Curator Tool.

Database configuration

Update environment variables or the myconfig.properties file to configure the JDBC driver and Hibernate dialect. The example below configures GRIN-Global Server to run against MariaDB or mysql server:

db.dataviewSql=mysql
db.url=jdbc:mysql://localhost/gringlobal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false&serverTimezone=UTC
db.driverClassName=com.mysql.cj.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQL8Dialect
db.username=root
db.password=
db.showSql=false

License and Disclaimer

This software is licensed under the Apache License, Version 2.0 (the "License").

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.