README.md 8.49 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
- 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
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.53/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.53/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 124 125
### A Brief Tour

(go over the general types of default routes)

126 127
- `_ops` routes

Corey O'Connor's avatar
~  
Corey O'Connor committed
128 129 130 131
### Service Fragments

(instantiate a service fragment)

132
# Customization
Corey O'Connor's avatar
~  
Corey O'Connor committed
133

134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
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
153
addSbtPlugin("glngn" % "sbt-glngn" % "0.3.53")
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
~~~

- `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
172 173
# Kubernetes Deployment

Corey O'Connor's avatar
~  
Corey O'Connor committed
174 175 176
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
177

Corey O'Connor's avatar
~  
Corey O'Connor committed
178
Features:
Corey O'Connor's avatar
~  
Corey O'Connor committed
179 180 181 182 183

- 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
184
- automatic node removal for terminated containers
Corey O'Connor's avatar
~  
Corey O'Connor committed
185 186 187

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
189 190 191 192 193 194 195 196 197 198 199 200
## Image Build

(TODO: instructions using the sbt docker tool)

## Service Definition

(TODO: include openshift definition)

## Route Definition

(TODO: include openshift definition)

201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
## 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
250
# Security - Authentication and Authorization
Corey O'Connor's avatar
~  
Corey O'Connor committed
251

Corey O'Connor's avatar
Corey O'Connor committed
252 253
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
254

Corey O'Connor's avatar
~  
Corey O'Connor committed
255 256 257
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
258

Corey O'Connor's avatar
~  
Corey O'Connor committed
259 260 261
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
262 263
- Groups contain Users
- Users in Groups are all Members of that Group
Corey O'Connor's avatar
Corey O'Connor committed
264
- Specific Users in a group are Operators
Corey O'Connor's avatar
Corey O'Connor committed
265 266
- 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
267 268 269 270 271

## Prerequisites

In order to use authentication or authorization:

Corey O'Connor's avatar
~  
Corey O'Connor committed
272 273
- 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
274

275 276
# References

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