README.md 5.9 KB
Newer Older
1
glngn server is an extensible business process application server. Similar to 
Corey O'Connor's avatar
Corey O'Connor committed
2 3 4
Microsoft Access or Apple FileMaker, but designed for event sourced business services with a code-first philosophy.
A standalone application with an approachable extension SDK is provided. 
Applications developed with glngn server can be easily deployed to a kubernetes cluster for sharing.
5

Corey O'Connor's avatar
~  
Corey O'Connor committed
6
- Support available from the [DogHeadBone LLC](mailto:support@dogheadbone.com) company
Corey O'Connor's avatar
Corey O'Connor committed
7
- Useful built-in services
8
- Easy event captures
Brett O'Connor's avatar
Brett O'Connor committed
9
- Predictable REST interface with an OpenAPI schema
10
- A [high level extension API](http://docs.glngn.com) for Scala service developers.
11 12 13
  (Plain, typed akka and zio interfaces are provided.)
- Simple persistence features
- Simple Kubernetes (k8s) cluster deployments. In addition to some custom automation, akka
Corey O'Connor's avatar
~  
Corey O'Connor committed
14
  management tools are included. OpenShift is also supported.
15

Corey O'Connor's avatar
Corey O'Connor committed
16
Sound good so far? Excellent! Let's start with basic, interactive usage of the standalone application.
17

18 19 20 21 22 23 24 25 26 27 28 29 30 31
# Developer Guide

This document is focused on usage and not extension of the application. Developers may be more interested in the 

- [development guide](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Customization.md)
- [development error help](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/CompileErrorHelp.md)

The implementation and extension API is familiar to Scala service developers. To a large
degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  A few of the niceties 
included:

- Cluster is enabled and established without additional configuration.
- Logging and data marshalling are configured appropriately. 
- Additional error tracking and handling.
32

Corey O'Connor's avatar
~  
Corey O'Connor committed
33
# Standalone Application
34

Corey O'Connor's avatar
~  
Corey O'Connor committed
35
prerequisites:
Corey O'Connor's avatar
Corey O'Connor committed
36

Corey O'Connor's avatar
Corey O'Connor committed
37
- java runtime version 8 or above. 
38
- agreement to the [Developer License](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Developer%20License%20v1.rtf?inline=false) This license is also included in the jar archive.
39 40 41

## Download

Corey O'Connor's avatar
Corey O'Connor committed
42
Prior to downloading, read and agree to the [Developer License agreement](https://gitlab.com/glngn/glngn-server-examples/raw/master/docs/Developer%20License%20v1.rtf?inline=false).
Corey O'Connor's avatar
~  
Corey O'Connor committed
43

jenkins's avatar
jenkins committed
44
- download [the latest release](https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.127/jars/glngn-server-assembly_2.12-assembly.jar)
45 46

```bash
jenkins's avatar
jenkins committed
47
curl -L -o glngn-server-assembly.jar https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.127/jars/glngn-server-assembly_2.12-assembly.jar
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
```

## Command Help

Run using java and pass `--help` to see usage information:

```bash
$ java -jar ./glngn-server-assembly.jar --help
Usage: glngn-server [options] [command] [command options]
  --port  <int?>
  --disable-ops  <bool>

Commands: print-config; print-full-config; run; version

Command: print-config
Usage: glngn-server print-config

Command: print-full-config
Usage: glngn-server print-full-config

Command: run
Usage: glngn-server run
  --state-dir  <string?>
  --exit-immediately  <bool>
  --initial-node-count  <int>
  --heap-dump-on-init  <bool>

Command: version
Usage: glngn-server version

Corey O'Connor's avatar
Corey O'Connor committed
78
Use of this software is agreement with the included Application Developer License.
79 80 81 82
```

## Running

83 84 85
Note: For consistency within the docs, the port 10000 is requested using `--port 10000`. If this option is
not provided a free port will automatically be selected.

Corey O'Connor's avatar
Corey O'Connor committed
86
Let's run the server configured to store data at `./starter.state`. In a terminal session:
87 88 89

```bash
$ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
90
INFO  use of this software is agreement with the included Developer License.
91
...
Corey O'Connor's avatar
~  
Corey O'Connor committed
92
[lots of output]
93
...
Corey O'Connor's avatar
~  
Corey O'Connor committed
94
INFO  glngn.server.host.ServerApp$  - application is listening at http://localhost:10000
95 96
```

97 98 99
At this point the standalone server is initialized and ready.

See [docs/Deep Dives](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/DeepDives.md) 
Corey O'Connor's avatar
Corey O'Connor committed
100
for more details on what happened.
Corey O'Connor's avatar
Corey O'Connor committed
101

Corey O'Connor's avatar
~  
Corey O'Connor committed
102 103 104 105
Hit control-C, or TERM the process (there is only one), to shut down the server. This will take a bit
for a nice, coordinated shutdown. Which is preferred. That said, the server is configured to attempt
recovery from sudden terminations. Such as killing a container in a kubernetes cluster.

Corey O'Connor's avatar
Corey O'Connor committed
106 107
## Examining a Running Server

Corey O'Connor's avatar
Corey O'Connor committed
108
Even in this default configuration the server provides useful routes:
Corey O'Connor's avatar
Corey O'Connor committed
109

Corey O'Connor's avatar
~  
Corey O'Connor committed
110
### Health Check
Corey O'Connor's avatar
Corey O'Connor committed
111 112

```bash
113
$ curl http://localhost:10000/healthz.txt
Corey O'Connor's avatar
Corey O'Connor committed
114 115 116
OK
```

Corey O'Connor's avatar
~  
Corey O'Connor committed
117 118
This will only return status 200 OK if the server is able to handle requests. Not terribly
interesting so far, but we haven't done much! Nice to verify the server health before proceeding tho.
Corey O'Connor's avatar
Corey O'Connor committed
119

Corey O'Connor's avatar
Corey O'Connor committed
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
Worth pointing out that we implicitly requested the text representation of the resource using a `.txt` 
suffix. We could have requested another representation, such as json, explicitly or implicitly:

```bash
$ curl -H 'Accept: text/plain' localhost:10000/healthz
OK

$ curl -H 'Accept: application/json' localhost:10000/healthz
{
  "memStats" : {
[...]
  "ok" : true
}
$ curl localhost:10000/healthz.json
{
  "memStats" : {
[...]
  "ok" : true
}
```

This pattern is supported throughout: Endpoints will have suffixed versions that imply the expected
representation.

Corey O'Connor's avatar
Corey O'Connor committed
144 145
### OpenAPI schema

Corey O'Connor's avatar
Corey O'Connor committed
146
Let's query for the API schema to see what other endpoints there are:
Corey O'Connor's avatar
~  
Corey O'Connor committed
147

Corey O'Connor's avatar
Corey O'Connor committed
148 149
```bash
$ curl http://localhost:10000/openapi.json
150 151
{
  "openapi" : "3.0.1",
Corey O'Connor's avatar
Corey O'Connor committed
152 153 154 155 156 157 158 159 160
  "info" : {
    "title" : "dynamic",
    "version" : "0.1"
  },
  "paths": {
    "/healthz": {
[...]
  }
}
161
[...]
Corey O'Connor's avatar
Corey O'Connor committed
162
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
163

Corey O'Connor's avatar
Corey O'Connor committed
164 165 166 167
Only a few paths are highlighted in the sample output above. Let's touch on those briefly:

1. The `/healthz` route. We've already tried that one

Corey O'Connor's avatar
~  
Corey O'Connor committed
168 169
### A Brief Tour

Corey O'Connor's avatar
Corey O'Connor committed
170
TODO: Go over the general types of default routes)
Corey O'Connor's avatar
~  
Corey O'Connor committed
171

Corey O'Connor's avatar
Corey O'Connor committed
172 173 174 175 176 177 178 179
- `_ops` routes - routes prefixed with a `_`. These are automatically generated.

- `/$GROUP/_ops`
- `/$GROUP/$SERVICE/_ops`

### Groups

TODO: show dynamic instantiation of a group
180

Corey O'Connor's avatar
~  
Corey O'Connor committed
181 182
### Service Fragments

Corey O'Connor's avatar
Corey O'Connor committed
183
TODO: show dynamic instantiation of a service fragment under a group