README.md

glngn server is an extensible business process application server. Similar to 
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.

- Support available from the [DogHeadBone LLC](mailto:support@dogheadbone.com) company
- Useful built-in services
- Easy event captures
- Predictable REST interface with an OpenAPI schema
- A [high level extension API](http://docs.glngn.com) for Scala service developers.
  (Plain, typed akka and zio interfaces are provided.)
- Simple persistence features
- Simple Kubernetes (k8s) cluster deployments. In addition to some custom automation, akka
  management tools are included. OpenShift is also supported.

Sound good so far? Excellent! Let's start with basic, interactive usage of the standalone application.

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

# Standalone Application

prerequisites:

- java runtime version 8 or above. 
- 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.

## Download

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

- 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)

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

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

Use of this software is agreement with the included Application Developer License.
```

## Running

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.

Let's run the server configured to store data at `./starter.state`. In a terminal session:

```bash
$ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
INFO  use of this software is agreement with the included Developer License.
...
[lots of output]
...
INFO  glngn.server.host.ServerApp$  - application is listening at http://localhost:10000
```

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 details on what happened.

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.

## Examining a Running Server

Even in this default configuration the server provides useful routes:

### Health Check

```bash
$ curl http://localhost:10000/healthz.txt
OK
```

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.

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.

### OpenAPI schema

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

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

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

### A Brief Tour

TODO: Go over the general types of default routes)

- `_ops` routes - routes prefixed with a `_`. These are automatically generated.

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

### Groups

TODO: show dynamic instantiation of a group

### Service Fragments

TODO: show dynamic instantiation of a service fragment under a group