README.md 4.39 KB
Newer Older
1 2 3 4 5
glngn server is a business process as a service rapid development system. The goal is to provide a
tool akin to Microsoft Access or Apple FileMaker (but scalable) for event sourced business
services. In addition to a library, a standalone application is provided that is capable of providing
utility with minimal ceremony. This can be customized with a simple API. As well as deployed to a
kubernetes cluster should those advantages be required.
Corey O'Connor's avatar
Corey O'Connor committed
6

7 8 9
The implementation and APIs should be familiar to Scala service developers. To a large degree, glngn
server is a nice, pre-configured typed akka plus ZIO server.

Corey O'Connor's avatar
~  
Corey O'Connor committed
10
- both typed akka and zio runtimes are provided. Use whichever suites your domain
Corey O'Connor's avatar
Corey O'Connor committed
11 12
- simplified persistence configuration
- simplified kubernetes cluster deployments. In addition to some custom automation, the akka
Corey O'Connor's avatar
~  
Corey O'Connor committed
13
  management tools are included
Corey O'Connor's avatar
Corey O'Connor committed
14
- OpenAPI support (provided by tapir)
15 16 17 18 19 20 21 22 23
- commercial support from the [Dog Head Bone](mailto:support@dogheadbone.com) company

Sound good so far? Cool! Let's start with basic, interactive usage.

# Standalone

prerequisites: java runtime version 8 or above

The `glngn-server.sh` and `glngn-server-assembly.jar` files can be executed to run a server with a
Corey O'Connor's avatar
~  
Corey O'Connor committed
24
default configuration. To start with running a customized server skip to [customization](#customization).
25 26 27

## Download

jenkins's avatar
jenkins committed
28
First, download [the latest release](https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.31/jars/glngn-server-assembly_2.12-assembly.jar)
29 30

```bash
jenkins's avatar
jenkins committed
31
$ curl -L -o glngn-server-assembly.jar https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.31/jars/glngn-server-assembly_2.12-assembly.jar
32 33 34 35 36 37 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
```

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

```

## Running

Corey O'Connor's avatar
Corey O'Connor committed
66
Let's run the server configured to store data at `./starter.state`. In a terminal session:
67 68 69 70

```bash
$ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
...
Corey O'Connor's avatar
~  
Corey O'Connor committed
71
[lots of output]
72 73 74 75
...
INFO  glngn.server.app.ServerApp$  - application is listening at http://localhost:10000
```

Corey O'Connor's avatar
~  
Corey O'Connor committed
76
For consistency with the docs, the port 10000 is requested using `--port 10000`. If this option is
Corey O'Connor's avatar
Corey O'Connor committed
77 78
not provided a free port will automatically be selected.

Corey O'Connor's avatar
~  
Corey O'Connor committed
79 80 81 82
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
83 84 85 86
## 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
87
### Health Check
Corey O'Connor's avatar
Corey O'Connor committed
88 89 90 91 92 93

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
94 95
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
96 97 98

### OpenAPI schema

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

Corey O'Connor's avatar
Corey O'Connor committed
101 102 103 104
```bash
$ curl http://localhost:10000/openapi.json
...
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
105

Corey O'Connor's avatar
~  
Corey O'Connor committed
106 107 108 109 110 111 112 113
### A Brief Tour

(go over the general types of default routes)

### Service Fragments

(instantiate a service fragment)

114
# Customization
Corey O'Connor's avatar
~  
Corey O'Connor committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131

# Kubernetes Deployment

We've designed glngn server to be nice to deploy and operate using kubernetes. The priority has been
on the standalone use, this is even more of a work in progress. The usage we are targetting is small
to medium deployments.

Current features:

- bootstrapping and lookup, using akka management, is preconfigured
- memory and threadpools tuned for containers
- provided routes for liveness and readiness probes
- separate port for internal cluster operations
- automatic removal nodes from the cluster for terminated containers

Internally, we build containers using nix and deploy to OpenShift. How would you'd like container
builds supported? Let us know at [support@dogheadbone.com](mailto:support@dogheadbone.com)