README.md 4.76 KB
Newer Older
Corey O'Connor's avatar
Corey O'Connor committed
1 2 3 4 5
glngn server is a business process as a service rapid development application. Conceptually similar
to Microsoft Access or Apple FileMaker (but scalable!) for event sourced business services. A
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 9 10
- Useful built in tools
- Easy event capture
- Friendly REST interace with an OpenAPI schema
Corey O'Connor's avatar
Corey O'Connor committed
11
- Plain, typed akka and zio runtimes are provided. Use whichever suites your domain
Corey O'Connor's avatar
~  
Corey O'Connor committed
12
- Simplified persistence
Corey O'Connor's avatar
Corey O'Connor committed
13
- Simplified Kubernetes (k8s) cluster deployments. In addition to some custom automation, the 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? Cool! Let's start with basic, interactive usage of the standalone application.
17

Corey O'Connor's avatar
Corey O'Connor committed
18 19 20
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
21
[customization](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Customization.md)
22

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

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

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

## Download

32
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
33

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

```bash
jenkins's avatar
jenkins committed
37
curl -L -o glngn-server-assembly.jar https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.90/jars/glngn-server-assembly_2.12-assembly.jar
38 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
```

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

## Running

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

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

87 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) 
for more information on what exactly that means.
Corey O'Connor's avatar
Corey O'Connor committed
91

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

Even in this default configuration the server provides a few useful routes:

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

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

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

### OpenAPI schema

Corey O'Connor's avatar
~  
Corey O'Connor committed
112 113
Let's query for the (current) API schema to see what else there is:

Corey O'Connor's avatar
Corey O'Connor committed
114 115
```bash
$ curl http://localhost:10000/openapi.json
116 117 118 119 120 121 122
{
  "openapi" : "3.0.1",
    "info" : {
      "title" : "dynamic",
      "version" : "0.1"
    }
[...]
Corey O'Connor's avatar
Corey O'Connor committed
123
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
124

Corey O'Connor's avatar
~  
Corey O'Connor committed
125 126
### A Brief Tour

Corey O'Connor's avatar
Corey O'Connor committed
127
TODO: o over the general types of default routes)
Corey O'Connor's avatar
~  
Corey O'Connor committed
128

Corey O'Connor's avatar
Corey O'Connor committed
129 130 131 132 133 134 135 136
- `_ops` routes - routes prefixed with a `_`. These are automatically generated.

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

### Groups

TODO: show dynamic instantiation of a group
137

Corey O'Connor's avatar
~  
Corey O'Connor committed
138 139
### Service Fragments

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