|
|
# 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!
|
|
|
|
|
|
# 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 the server
|
|
|
|
|
|
**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.
|
|
|
|
|
|
```bash
|
|
|
dockerhub.croptrust.org/grin-global/grin-global-server:2021.10
|
|
|
```
|
|
|
|
|
|
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 **GG-CE** to use the MSSQL database.
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
The **GG-CE** 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
|
|
|
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`)
|
|
|
|
|
|
Start **GG-CE Server** as a Docker container:
|
|
|
|
|
|
```bash
|
|
|
# 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
|
|
|
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 "HOST_NAME=${YOUR_DOCKER_HOST_IP}" \
|
|
|
-e "HOST_NAMEANDPORT=${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:2021.10
|
|
|
```
|
|
|
|
|
|
**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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
## Upgrading to newer version
|
|
|
|
|
|
To get the latest version of the image you need to pull the latest *edge* image and recreate your container:
|
|
|
|
|
|
```bash
|
|
|
docker pull dockerhub.croptrust.org/grin-global/grin-global-server:2021.11-edge
|
|
|
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: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:
|
|
|
|
|
|
```bash
|
|
|
# Current development version
|
|
|
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge
|
|
|
```
|
|
|
|
|
|
# Populating the database
|
|
|
|
|
|
Once you can connect to your GG-CE Server, navigate to the Admin section and:
|
|
|
|
|
|
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
|
|
|
|
|
|
Consider installing [GG-CE Web](https://gitlab.croptrust.org/grin-global/grin-global-ui).
|
|
|
|
|
|
|
|
|
|
|
|
# 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.
|
|
|
|
|
|
|
|
|
```bash
|
|
|
# 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):
|
|
|
|
|
|
```sql
|
|
|
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
|
|
|
|
|
|
```sh
|
|
|
# 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:
|
|
|
|
|
|
```properties
|
|
|
db.url=jdbc:sqlserver://localhost:1433;DatabaseName=gringlobal
|
|
|
db.username=sa
|
|
|
db.password=sa1
|
|
|
```
|
|
|
|
|
|
Start the embedded web server from the terminal:
|
|
|
|
|
|
```bash
|
|
|
# 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:
|
|
|
|
|
|
```properties
|
|
|
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. |