README.md 5.52 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

10 11
- plain, typed akka and zio runtimes are provided. Use whichever suites your domain.
- simplified event persistence
Corey O'Connor's avatar
Corey O'Connor committed
12
- 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
14
- OpenAPI support (akka http server with tapir)
15 16
- commercial support from the [Dog Head Bone](mailto:support@dogheadbone.com) company

17 18 19
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).
20 21 22 23 24 25

# 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
26
default configuration.
27 28 29

## Download

jenkins's avatar
jenkins committed
30
First, 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)
31 32

```bash
jenkins's avatar
jenkins committed
33
$ 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
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 67
```

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

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

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

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

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

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

### OpenAPI schema

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

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

Corey O'Connor's avatar
~  
Corey O'Connor committed
114 115 116 117
### A Brief Tour

(go over the general types of default routes)

118 119
- `_ops` routes

Corey O'Connor's avatar
~  
Corey O'Connor committed
120 121 122 123
### Service Fragments

(instantiate a service fragment)

124
# Customization
Corey O'Connor's avatar
~  
Corey O'Connor committed
125

126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
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
145
addSbtPlugin("glngn" % "sbt-glngn" % "0.3.36")
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
~~~

- `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
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
# 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)
180

Corey O'Connor's avatar
~  
Corey O'Connor committed
181 182 183 184 185 186
# Authentication and Authorization

In order to use authentication:

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

187 188 189
# References

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