README.md 7.26 KB
Newer Older
Matija Obreza's avatar
Matija Obreza committed
1
# GG-CE Server
Matija Obreza's avatar
Matija Obreza committed
2

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

Matija Obreza's avatar
Matija Obreza committed
5
This is a Java implementation of the GRIN-Global middle-tier.
Matija Obreza's avatar
Matija Obreza committed
6
The APIs provided by this implementation are mostly compatible with
Matija Obreza's avatar
Matija Obreza committed
7
8
the original implementation of the .Net GRIN-Global.Server.

Matija Obreza's avatar
Matija Obreza committed
9
10
11
Please check https://gitlab.croptrust.org/grin-global/grin-global-server/-/releases for 
information on new releases!

Matija Obreza's avatar
Matija Obreza committed
12
13
# Running the server

14
**GG-CE Server** is available as a Docker image `dockerhub.croptrust.org/grin-global/grin-global-server:latest`.
Matija Obreza's avatar
Matija Obreza committed
15
16
17
This allows for easy management and updating to newer versions.

```bash
18
dockerhub.croptrust.org/grin-global/grin-global-server:latest
Matija Obreza's avatar
Matija Obreza committed
19
```
20
21
22
23
24

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.

25
26
The server will initialize the database schema and populate it with initial
data automatically. Alternatively, upgrade your existing GRIN-Global Database using the standard
27
28
29
installer and then configure **GG-CE** to use the MSSQL database.


30
## Configuration
31
32
33
34
35
36

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
37
1. The URL address where **GG-CE 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`)
Matija Obreza's avatar
Matija Obreza committed
38
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`)
39
40

Start **GG-CE Server** as a Docker container:
41
42

```bash
43
# Pull latest image
44
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:latest
45
46
47
48
49

# Create a data volume
docker volume create ggce-server-data

# Start GRIN-Global Server
50
# 
51
52
# Make sure that address for MSSQL "jdbc:sqlserver://172.17.0.2:1433" is
# equal to ip from `docker inspect mssql-ggce` output
53
54
#
# Windows: Remove the \ from the command below when using cmd.exe!
55
56
docker run --rm --name 'ggce-server' \
 -p 8081:8080 \
Matija Obreza's avatar
Matija Obreza committed
57
 -e "DB_URL=jdbc:sqlserver://<MSSQL>:1433;DatabaseName=ggce" \
58
59
 -e "DB_USERNAME=sa" \
 -e "DB_PASSWORD=YourStrong@Passw0rd" \
60
 -e "BASE_URL=http://${YOUR_DOCKER_HOST_IP}:8081" \
Matija Obreza's avatar
Matija Obreza committed
61
 -e "FRONTEND_URL=http://${YOUR_DOCKER_HOST_IP}:3000" \
62
63
 -e "DATA_DIR=/data/gringlobal" \
 -v ggce-server-data:/data/gringlobal \
64
 dockerhub.croptrust.org/grin-global/grin-global-server:latest
65
66
```

67
**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.
68

Matija Obreza's avatar
Matija Obreza committed
69
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.
70
71
This makes your GG-CE server accessible at http://YOUR_DOCKER_HOST_IP:8081 and corresponds with variable `HOST_NAMEANDPORT` in the command above.

72
GG-CE 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:
73
74

```bash
75
docker run [...] -e 'CONTEXT_PATH=/gg-ce' -e 'BASE_URL=http://YOUR_DOCKER_HOST_IP:8081/gg-ce' [...]
76
```
77
78

When you see the message `[INFO] Started Jetty Server` you can connect to your own GG-CE instance on the IP of the host
79
and port **8081** (if you used the command above) at the `BASE_URL` (http://YOUR_DOCKER_HOST_IP:8081.
80

81

82
83
## Upgrading to newer version

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

```bash
87
docker pull dockerhub.croptrust.org/grin-global/grin-global-server:latest
88
89
90
docker stop ggce-server
docker remove ggce-server # if the container name is still defined
docker run... # as above
91
92
```

93
94
## Next release

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

```bash
99
# Preview of the latest development release
100
101
102
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge
```

103
104
105
106
107
108
109
110
111
112
113
114
# 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).


115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# 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
```



149
# For developers
150

151
152
153
154
155
156
157
158
159
160
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.

Matija Obreza's avatar
Matija Obreza committed
161
162
Copy the `myconfig.properties.example` to `myconfig.properties` in
the project folder. Update the configuration options to connect to
163
your MSSQL _gringlobal_ database:
Matija Obreza's avatar
Matija Obreza committed
164
165
166
167
168
169
170
171
172
173

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

Start the embedded web server from the terminal:

```bash
174
175
# Switch to server module
cd server/
176
mvn -DskipTests=true jetty:run
Matija Obreza's avatar
Matija Obreza committed
177
178
179
```

Start the Curator Tool. Add a new GRIN-Global server with display name
180
_java_ and server name (or IP Address) `localhost:8080`.
Matija Obreza's avatar
Matija Obreza committed
181
182
183

Skip "Test Server Address".

184
Connect to the _java_ server and enjoy the Curator Tool.
185

186
## Database configuration
187

188
189
190
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:
191

Matija Obreza's avatar
Matija Obreza committed
192
```properties
Matija Obreza's avatar
Matija Obreza committed
193
194
195
196
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
Matija Obreza's avatar
Matija Obreza committed
197
198
199
200
201
db.username=root
db.password=
db.showSql=false
```

202
203
204
205
206
207
208
209
210
211
212
213

# 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.