README.md 3.17 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 10
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.

- clustering and coordination is provided by typed Akka
Corey O'Connor's avatar
Corey O'Connor committed
11 12 13 14 15
- both a typed akka and zio runtime are provided. Use whichever suites your domain.
- simplified persistence configuration
- simplified kubernetes cluster deployments. In addition to some custom automation, the akka
  management tools are included.
- OpenAPI support (provided by tapir)
16 17 18 19 20 21 22 23 24
- 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
25
default configuration. To start with running a customized server skip to [customization](#customization).
26 27 28

## Download

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

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

## 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
67
Let's run the server configured to store data at `./starter.state`. In a terminal session:
68 69 70 71

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
77
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
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
not provided a free port will automatically be selected.

## Examining a Running Server

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

### Health

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

This will always return status 200 OK if the server is able to handle requests. If there is a issue
this will not return OK.

### OpenAPI schema

```bash
$ curl http://localhost:10000/openapi.json
...
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
100

101
# Customization