README.md 5.54 KB
Newer Older
Corey O'Connor's avatar
Corey O'Connor committed
1 2
glngn server is a business process as a service rapid development application. Conceptually, glngn server is a programmable and scalable
Microsoft Access or Apple FileMaker for event sourced business services. A
Corey O'Connor's avatar
Corey O'Connor committed
3 4 5
standalone application is provided that is useful with minimal ceremony. In addition to an
approachable extension API.  This solution can also be deployed to a kubernetes cluster for sharing
and reliability.
6

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

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

Corey O'Connor's avatar
Corey O'Connor committed
19 20 21
The implementation and extension API might be familiar to Scala service developers. To a large
degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  To start
with the extension API and running a customized server see
Corey O'Connor's avatar
Corey O'Connor committed
22
[customization](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Customization.md)
23

Corey O'Connor's avatar
~  
Corey O'Connor committed
24
# Standalone Application
25

Corey O'Connor's avatar
~  
Corey O'Connor committed
26
prerequisites:
Corey O'Connor's avatar
Corey O'Connor committed
27 28

- java runtime version 8 or above
29
- 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.
30 31 32

## Download

33
Prior to downloading, read and agree to the [Developer License aggreement](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
34

jenkins's avatar
jenkins committed
35
- download [the latest release](https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.104/jars/glngn-server-assembly_2.12-assembly.jar)
36 37

```bash
jenkins's avatar
jenkins committed
38
curl -L -o glngn-server-assembly.jar https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.104/jars/glngn-server-assembly_2.12-assembly.jar
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
```

## 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
69
Use of this software is agreement with the included Application Developer License.
70 71 72 73
```

## Running

74 75 76
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
77
Let's run the server configured to store data at `./starter.state`. In a terminal session:
78 79 80

```bash
$ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
81
INFO  use of this software is agreement with the included Developer License.
82
...
Corey O'Connor's avatar
~  
Corey O'Connor committed
83
[lots of output]
84 85 86 87
...
INFO  glngn.server.app.ServerApp$  - application is listening at http://localhost:10000
```

88 89 90
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
91
for more details on what happened.
Corey O'Connor's avatar
Corey O'Connor committed
92

Corey O'Connor's avatar
~  
Corey O'Connor committed
93 94 95 96
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
97 98
## Examining a Running Server

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
101
### Health Check
Corey O'Connor's avatar
Corey O'Connor committed
102 103

```bash
104
$ curl http://localhost:10000/healthz.txt
Corey O'Connor's avatar
Corey O'Connor committed
105 106 107
OK
```

Corey O'Connor's avatar
~  
Corey O'Connor committed
108 109
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
110

Corey O'Connor's avatar
Corey O'Connor committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
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
135 136
### OpenAPI schema

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

Corey O'Connor's avatar
Corey O'Connor committed
139 140
```bash
$ curl http://localhost:10000/openapi.json
141 142
{
  "openapi" : "3.0.1",
Corey O'Connor's avatar
Corey O'Connor committed
143 144 145 146 147 148 149 150 151
  "info" : {
    "title" : "dynamic",
    "version" : "0.1"
  },
  "paths": {
    "/healthz": {
[...]
  }
}
152
[...]
Corey O'Connor's avatar
Corey O'Connor committed
153
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
154

Corey O'Connor's avatar
Corey O'Connor committed
155 156 157 158
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
159 160
### A Brief Tour

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

Corey O'Connor's avatar
Corey O'Connor committed
163 164 165 166 167 168 169 170
- `_ops` routes - routes prefixed with a `_`. These are automatically generated.

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

### Groups

TODO: show dynamic instantiation of a group
171

Corey O'Connor's avatar
~  
Corey O'Connor committed
172 173
### Service Fragments

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