README.md 6.86 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
Matija Obreza's avatar
Matija Obreza committed
37
38
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`)
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
50
51
52
53

# 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 \
Matija Obreza's avatar
Matija Obreza committed
54
 -e "DB_URL=jdbc:sqlserver://<MSSQL>:1433;DatabaseName=ggce" \
55
56
 -e "DB_USERNAME=sa" \
 -e "DB_PASSWORD=YourStrong@Passw0rd" \
Matija Obreza's avatar
Matija Obreza committed
57
58
59
 -e "HOST_NAME=${YOUR_DOCKER_HOST_IP}" \
 -e "HOST_NAMEANDPORT=${YOUR_DOCKER_HOST_IP}:8081" \
 -e "FRONTEND_URL=http://${YOUR_DOCKER_HOST_IP}:3000" \
60
61
 -e "DATA_DIR=/data/gringlobal" \
 -v ggce-server-data:/data/gringlobal \
62
 dockerhub.croptrust.org/grin-global/grin-global-server:latest
63
64
```

65
**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.
66

Matija Obreza's avatar
Matija Obreza committed
67
68
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.
69
70

When you see the message `[INFO] Started Jetty Server` you can connect to your own GG-CE instance on the IP of the host
Matija Obreza's avatar
Matija Obreza committed
71
and port **8081** (if you used the command above) at http://YOUR_DOCKER_HOST_IP:8081.
72

73

74
75
## Upgrading to newer version

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

```bash
79
docker pull dockerhub.croptrust.org/grin-global/grin-global-server:latest
80
81
82
docker stop ggce-server
docker remove ggce-server # if the container name is still defined
docker run... # as above
83
84
```

85
86
## Next release

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

```bash
91
# Preview of the latest development release
92
93
94
docker image pull dockerhub.croptrust.org/grin-global/grin-global-server:edge
```

95
96
97
98
99
100
101
102
103
104
105
106
# 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).


107
108
109
110
111
112
113
114
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

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



141
# For developers
142

143
144
145
146
147
148
149
150
151
152
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
153
154
Copy the `myconfig.properties.example` to `myconfig.properties` in
the project folder. Update the configuration options to connect to
155
your MSSQL _gringlobal_ database:
Matija Obreza's avatar
Matija Obreza committed
156
157
158
159
160
161
162
163
164
165

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

Start the embedded web server from the terminal:

```bash
166
167
# Switch to server module
cd server/
168
mvn -DskipTests=true jetty:run
Matija Obreza's avatar
Matija Obreza committed
169
170
171
```

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

Skip "Test Server Address".

176
Connect to the _java_ server and enjoy the Curator Tool.
177

178
## Database configuration
179

180
181
182
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:
183

Matija Obreza's avatar
Matija Obreza committed
184
```properties
Matija Obreza's avatar
Matija Obreza committed
185
186
187
188
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
189
190
191
192
193
db.username=root
db.password=
db.showSql=false
```

194
195
196
197
198
199
200
201
202
203
204
205

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