README.md 7.98 KB
Newer Older
Corey O'Connor's avatar
Corey O'Connor committed
1
glngn server is an extensible business process application server. Similar to
Corey O'Connor's avatar
Corey O'Connor committed
2
Microsoft Access or Apple FileMaker, but designed for event sourced business services with a code-first philosophy.
Corey O'Connor's avatar
Corey O'Connor committed
3
A standalone application with an approachable extension SDK is provided.
Corey O'Connor's avatar
Corey O'Connor committed
4
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
# Developer Guide

Corey O'Connor's avatar
Corey O'Connor committed
20
This document is focused on usage and not extension of the application. Developers may be more interested in the
21 22 23 24 25

- [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
Corey O'Connor's avatar
Corey O'Connor committed
26
degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  A few of the niceties
27 28 29
included:

- Cluster is enabled and established without additional configuration.
Corey O'Connor's avatar
Corey O'Connor committed
30
- Logging and data marshalling are configured appropriately.
31
- 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.130/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.130/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 a 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
At this point the standalone server is initialized and ready.

Corey O'Connor's avatar
Corey O'Connor committed
99
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
## Usage
Corey O'Connor's avatar
Corey O'Connor committed
107

Corey O'Connor's avatar
Corey O'Connor committed
108 109 110
The glngn server provides a REST API with an [OpenAPI](https://www.openapis.org/) specification.
This API supports the built-in features of glngn server as well as any additional features added
by extensions.
Corey O'Connor's avatar
Corey O'Connor committed
111

Corey O'Connor's avatar
Corey O'Connor committed
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 141 142 143 144 145
If you are looking for a GUI for glngn server [please let us know](mailto:support@dogheadbone.com).

### OpenAPI schema

Let's query for the API schema to see what endpoints there are:

```bash
$ curl http://localhost:10000/openapi.json
{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "dynamic",
    "version" : "0.1"
  },
  "paths": {
    "/healthz": ...
    "/_ops/groups": ...
[...]
  }
}
[...]
```

A brief overview:

1. The `/healthz` route. We'll try that one below.
2. The `/_ops/groups` route. This is an operations route for the groups in glngn server. All services
are placed under a group. The default configuration does not include any groups (or services). This
will be the first route we try in the `API Tour`.

### Multiple Representations

The `/healthz` route will only return status 200 OK if the server is able to handle requests.
This is also a nice example to demonstrate how glngn server supports multiple representations:
Corey O'Connor's avatar
Corey O'Connor committed
146 147

```bash
148
$ curl http://localhost:10000/healthz.txt
Corey O'Connor's avatar
Corey O'Connor committed
149 150 151
OK
```

Corey O'Connor's avatar
Corey O'Connor committed
152 153
Note the use of a `.txt` extension to request a text representation. We could have
requested another representation, such as `json`, explicitly or implicitly:
Corey O'Connor's avatar
Corey O'Connor committed
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175

```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
176
### API Tour
Corey O'Connor's avatar
~  
Corey O'Connor committed
177

Corey O'Connor's avatar
Corey O'Connor committed
178 179
The API conventions enforced by glngn server:

Corey O'Connor's avatar
Corey O'Connor committed
180 181 182 183
- All routes prefixed with a `_` are operations routes. These are provided by glngn server.
- `/_ops/`
    - Deployment `_ops` routes
    - These are always available
Corey O'Connor's avatar
Corey O'Connor committed
184
    - EG: `/_ops/groups`: query and modify the available groups
Corey O'Connor's avatar
Corey O'Connor committed
185
- `/$GROUP/_ops`
Corey O'Connor's avatar
Corey O'Connor committed
186
    - Group `_ops` routes. These require a group, `$GROUP`, to be created
Corey O'Connor's avatar
Corey O'Connor committed
187
- `/$GROUP/$SERVICE/_ops`
Corey O'Connor's avatar
Corey O'Connor committed
188
    - Service fragment `_ops` routes, `/$GROUP/$SERVICE/_ops`, require the service fragment to be
Corey O'Connor's avatar
Corey O'Connor committed
189
    instantiated under the group
Corey O'Connor's avatar
Corey O'Connor committed
190
    - automatically generated for each instantiated service fragment
Corey O'Connor's avatar
Corey O'Connor committed
191
- `/$GROUP/$SERVICE/...`
Corey O'Connor's avatar
Corey O'Connor committed
192
    - All other routes under a service are provided by a Service Fragment's `endpoints`
Corey O'Connor's avatar
Corey O'Connor committed
193

Corey O'Connor's avatar
Corey O'Connor committed
194
### Create a Groups
Corey O'Connor's avatar
Corey O'Connor committed
195

Corey O'Connor's avatar
Corey O'Connor committed
196 197 198
The `/_ops/groups` endpoint is used to query the existing groups and create new groups.
All services are namespaced under a group. Before we can instantiate and use a service we must
first create a group:
199

Corey O'Connor's avatar
Corey O'Connor committed
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
~~~
$ curl --data '{ "id": "accounts", "name": "Client Accounts" }' localhost:10000/_ops/groups
{
  "id" : {
    "txt" : "accounts"
  },
  "name" : "Client Accounts",
  "operators" : null
}
~~~

This creates a group with the logical name `accounts`. The endpoint responds with the
current definition of the group.

Which we can confirm by querying the `/_ops/groups` endpoint again:

~~~
$ curl localhost:10000/_ops/groups
{
  "accounts" : {
    "id" : {
      "txt" : "accounts"
    },
    "name" : "Cli Accounts",
    "operators" : null
  }
}
~~~

Note the `operators` attribute. Using the premium license server this would contain the users
authorized to access that group. The free license server ignores this attribute.

Corey O'Connor's avatar
Corey O'Connor committed
232
### Instantiate a Service Fragment
Corey O'Connor's avatar
~  
Corey O'Connor committed
233

Corey O'Connor's avatar
Corey O'Connor committed
234
TODO: show dynamic instantiation of a service fragment under a group
Corey O'Connor's avatar
Corey O'Connor committed
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

### Use a Service Fragment

TODO:

1. show dynamic instantiation of a service fragment in OpenAPI schema.
2. demo using the counter service fragment

### Capturing Events

TODO:

1. demo capturing unmodeled events:
    1. deployment-wide (?)
    2. group events
    3. service events
2. demo capturing a service modeled event