README.md 5.7 KB
Newer Older
1 2 3 4 5
glngn server is a business process as a service rapid development system. The tool is similar 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 useful 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
The implementation and APIs might be familiar to Scala service developers. To a large degree, glngn
server is a friendly, constrained, pre-configured typed akka plus ZIO server.
9

Corey O'Connor's avatar
Corey O'Connor committed
10
- Optional commercial support from the [DogHeadBone LLC](mailto:support@dogheadbone.com) company
Corey O'Connor's avatar
Corey O'Connor committed
11 12
- Painlessly capture business process data
- Plain, typed akka and zio runtimes are provided. Use whichever suites your domain
Corey O'Connor's avatar
Corey O'Connor committed
13
- Simplified event 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
Corey O'Connor's avatar
Corey O'Connor committed
16
- OpenAPI support
17

18 19 20
Sound good so far? Cool! Let's start with basic, interactive usage of the standalone server.

To start with running a customized server skip to [customization](#customization).
21 22 23

# Standalone

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

- java runtime version 8 or above
- agreement to the Application Developer License (link to license)
28 29

The `glngn-server.sh` and `glngn-server-assembly.jar` files can be executed to run a server with a
30
default configuration.
31 32 33

## Download

Corey O'Connor's avatar
Corey O'Connor committed
34
Prior to downloading read the Application Developer License aggreement (link to license). Then, download [the latest release](https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.36/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.36/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 68 69 70 71
```

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

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
82
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
83 84
not provided a free port will automatically be selected.

Corey O'Connor's avatar
~  
Corey O'Connor committed
85 86 87 88
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
89 90 91 92
## 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
93
### Health Check
Corey O'Connor's avatar
Corey O'Connor committed
94 95 96 97 98 99

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
100 101
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
102 103 104

### OpenAPI schema

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

Corey O'Connor's avatar
Corey O'Connor committed
107 108
```bash
$ curl http://localhost:10000/openapi.json
109 110 111 112 113 114 115
{
  "openapi" : "3.0.1",
    "info" : {
      "title" : "dynamic",
      "version" : "0.1"
    }
[...]
Corey O'Connor's avatar
Corey O'Connor committed
116
```
Corey O'Connor's avatar
~  
Corey O'Connor committed
117

Corey O'Connor's avatar
~  
Corey O'Connor committed
118 119 120 121
### A Brief Tour

(go over the general types of default routes)

122 123
- `_ops` routes

Corey O'Connor's avatar
~  
Corey O'Connor committed
124 125 126 127
### Service Fragments

(instantiate a service fragment)

128
# Customization
Corey O'Connor's avatar
~  
Corey O'Connor committed
129

130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
This repository is a series of different customizations.

1. `starter-0` - identical to the default
2. `starter-1` - an additional available service fragment
3. `starter-2` - a default group with a service fragment already instantiated
4. `starter-3` - same as starter-2 but configured for kubernetes deployment

## Minimum build setup

The build setup consists of:

- `project/plugins.sbt`:

~~~
resolvers += Resolver.url(
  "glngn server releases",
  url("https://glngn-server-releases.s3.amazonaws.com/releases")
)(Resolver.ivyStylePatterns)

jenkins's avatar
jenkins committed
149
addSbtPlugin("glngn" % "sbt-glngn" % "0.3.36")
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
~~~

- `build.sbt`:

~~~
lazy val `my-customizations` =
  glngn.sbt.StarterDeployment(
    "my-customizations",
    file("my-customizations"),
  )
~~~

- `project/build.properties`:

~~~
sbt.version=1.2.8
~~~

Corey O'Connor's avatar
~  
Corey O'Connor committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
# 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)
184

Corey O'Connor's avatar
~  
Corey O'Connor committed
185 186 187 188 189 190
# Authentication and Authorization

In order to use authentication:

- a server license for the appropriate number of operators is required.

191 192 193
# References

* for inspiration: https://enroute.osgi.org/tutorial/020-tutorial_qs.html