README.md 10.1 KB
Newer Older
Corey O'Connor's avatar
~  
Corey O'Connor committed
1
glngn server is a business process as a service rapid development system. Conceptually similar to
2 3 4 5
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
- support available 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
- automatic OpenAPI schema
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
prerequisites:
Corey O'Connor's avatar
Corey O'Connor committed
25 26

- java runtime version 8 or above
Corey O'Connor's avatar
Corey O'Connor committed
27
- agreement to the Application Developer License (TODO: link to license on site) This license is also included in the jar archive.
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 and agree to the Application Developer License aggreement (link to license).
Corey O'Connor's avatar
~  
Corey O'Connor committed
35

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

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

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

## Running

Corey O'Connor's avatar
Corey O'Connor committed
75
Let's run the server configured to store data at `./starter.state`. In a terminal session:
76 77 78

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

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
89 90 91 92
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
93 94 95 96
## 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
97
### Health Check
Corey O'Connor's avatar
Corey O'Connor committed
98 99 100 101 102 103

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
104 105
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
106 107 108

### OpenAPI schema

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

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
122 123
### A Brief Tour

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

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

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

### Groups

TODO: show dynamic instantiation of a group
134

Corey O'Connor's avatar
~  
Corey O'Connor committed
135 136
### Service Fragments

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

139
# Customization
Corey O'Connor's avatar
~  
Corey O'Connor committed
140

Corey O'Connor's avatar
Corey O'Connor committed
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
glngn server provided a programmable application experience: All dynamic 
operations described above can also be declared via Scala code. New service
fragments can be added as well.

## Deep Dive: On the use of an assembly

The default build uses an assembly, non-modular, glngn server library. This
provides a low complexity build for extensions that only need the included
libraries. See [the API documentation here](http://docs.glngn.com/latest/api/) 
for reference.

Assembly distributions are considered "a headache the moment your users step 
outside of Hello World". However, with glngn server those simple cases are often
useful and the convinience is valuable. 

In addition, the provided glngn server assembly has a high degree of assurance
that is difficult to provide with a modular build (at this time). The
assembly is built and verified against specific versions of dependent libraries.
The non-modular build permits adding or changing dependents. However, this
invalidates the prior assurances to a degree.

## Using only scalac


## Using sbt-glngn plugin

Using scalac directly is nice but the recommendation is to use the `sbt-glngn` 
sbt plugin. Very little code is required to start using this plugin. The 
interfaces provided also support easily moving to the modular build.

When the additional complexity of a modular build is appropriate, of course. :)

173 174 175 176 177 178
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
Corey O'Connor's avatar
Corey O'Connor committed
179 180
5. `modular-0` - same as starter-1 but using the modular libraries instead.

181 182 183 184 185 186 187 188 189 190 191 192 193

## 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
194
addSbtPlugin("glngn" % "sbt-glngn" % "0.3.55")
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
~~~

- `build.sbt`:

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

- `project/build.properties`:

~~~
Corey O'Connor's avatar
Corey O'Connor committed
210
sbt.version=1.3.3
211 212
~~~

Corey O'Connor's avatar
~  
Corey O'Connor committed
213 214
# Kubernetes Deployment

Corey O'Connor's avatar
~  
Corey O'Connor committed
215 216 217
We've designed glngn server to be nice to run and operate using kubernetes. The priority has been on
the standalone use, so this is more of a work in progress. The usage we are targeting is small to
medium deployments.
Corey O'Connor's avatar
~  
Corey O'Connor committed
218

Corey O'Connor's avatar
~  
Corey O'Connor committed
219
Features:
Corey O'Connor's avatar
~  
Corey O'Connor committed
220 221 222 223 224

- 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
Corey O'Connor's avatar
~  
Corey O'Connor committed
225
- automatic node removal for terminated containers
Corey O'Connor's avatar
~  
Corey O'Connor committed
226 227 228

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
230 231 232 233 234 235 236 237 238 239 240 241
## Image Build

(TODO: instructions using the sbt docker tool)

## Service Definition

(TODO: include openshift definition)

## Route Definition

(TODO: include openshift definition)

242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
## Storage

glngn server uses akka persistence for storage. The standalone mode is preconfigured to use
LevelDB. The kubernetes deployment mode supports Amazon's DynamoDB.

Deep Dive: Internally, akka persistence is used. The value add of glngn server is simplified
configuration and operations. At this time only DynamoDB and LevelDB are supported. Contact
[support@dogheadbone.com](mailto:support@dogheadbone.com) for information on supporting other akka
persistence backends.

### DynamoDB

With a deployment name `$NAME` in AWS `$REGION`:


1. in `application.conf`:

~~~
glngn.server {
    default-persistence = "dynamodb"

    dynamodb {
        URL = "https://dynamodb.$REGION.amazonaws.com"
        region = "$REGION"
        journal-table = "$NAME-journal"
        snapshot-table = "$NAME-snapshot"
    }
}
~~~

2. create DynamoDB tables `$NAME-journal` and `$NAME-snapshot`.

journal:

- partition key (hash key) of: name "par" ; type string
- sort key (range key) of: name "num" ; type number
- "table settings": default settings are fine to start. on-demand provisioning is supported.

snapshot:

- hash key of string type "par"
- range key of number type "seq"
- local secondary index, projecting all attributes, named "ts-idx" of:
- hash key of string type "par"
- range key of number type "ts"

The schema and existence of the tables will be verified on server startup. The server will not
initialize if the tables are invalid.

Corey O'Connor's avatar
Corey O'Connor committed
291
# Security - Authentication and Authorization
Corey O'Connor's avatar
~  
Corey O'Connor committed
292

Corey O'Connor's avatar
Corey O'Connor committed
293 294
In standalone mode, by default, glngn server runs in insecure mode. This means no authentication or
authorization is performed. All access is anonymous.
Corey O'Connor's avatar
~  
Corey O'Connor committed
295

Corey O'Connor's avatar
~  
Corey O'Connor committed
296 297 298
In secure mode glng server performs authorization and authentication. The rules are designed to be
predictable and familiar. EG: Given an endpoint path, the necessary authentication is clear from the
parts of the path; and the options resemble those of a network file server.
Corey O'Connor's avatar
Corey O'Connor committed
299

Corey O'Connor's avatar
~  
Corey O'Connor committed
300 301 302
Authentication and Authorization (AuthN/AuthZ) in glngn server is based around:

- All accessors are Anonymous or Users
Corey O'Connor's avatar
Corey O'Connor committed
303 304
- Groups contain Users
- Users in Groups are all Members of that Group
Corey O'Connor's avatar
Corey O'Connor committed
305
- Specific Users in a group are Operators
Corey O'Connor's avatar
Corey O'Connor committed
306 307
- All endpoints are, by default, only authenticated for Group Members
- All `_ops` endpoints are only authenticated for Operators of the Group
Corey O'Connor's avatar
Corey O'Connor committed
308 309 310 311 312

## Prerequisites

In order to use authentication or authorization:

Corey O'Connor's avatar
~  
Corey O'Connor committed
313 314
- Google is the only authentication provider supported at this time
- For more than 5 operators, a license key is required. Contact [support@dogheadbone.com](mailto:support@dogheadbone.com) for further information
Corey O'Connor's avatar
~  
Corey O'Connor committed
315

316 317
# References

Corey O'Connor's avatar
~  
Corey O'Connor committed
318
* inspiration for this document's structure - https://enroute.osgi.org/tutorial/020-tutorial_qs.html