Commit 0b0ac192 authored by Corey O'Connor's avatar Corey O'Connor
Browse files

expand on guide

parent 943e01da
glngn server is an extensible business process application server. Similar to
glngn server is an extensible business process application server. Similar to
Microsoft Access or Apple FileMaker, but designed for event sourced business services with a code-first philosophy.
A standalone application with an approachable extension SDK is provided.
A standalone application with an approachable extension SDK is provided.
Applications developed with glngn server can be easily deployed to a kubernetes cluster for sharing.
- Support available from the [DogHeadBone LLC](mailto:support@dogheadbone.com) company
......@@ -17,24 +17,24 @@ Sound good so far? Excellent! Let's start with basic, interactive usage of the s
# Developer Guide
This document is focused on usage and not extension of the application. Developers may be more interested in the
This document is focused on usage and not extension of the application. Developers may be more interested in the
- [development guide](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Customization.md)
- [development error help](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/CompileErrorHelp.md)
The implementation and extension API is familiar to Scala service developers. To a large
degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server. A few of the niceties
degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server. A few of the niceties
included:
- Cluster is enabled and established without additional configuration.
- Logging and data marshalling are configured appropriately.
- Logging and data marshalling are configured appropriately.
- Additional error tracking and handling.
# Standalone Application
prerequisites:
- java runtime version 8 or above.
- java runtime version 8 or above.
- agreement to the [Developer License](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Developer%20License%20v1.rtf?inline=false) This license is also included in the jar archive.
## Download
......@@ -83,7 +83,7 @@ Use of this software is agreement with the included Application Developer Licens
Note: For consistency within the docs, the port 10000 is requested using `--port 10000`. If this option is
not provided a free port will automatically be selected.
Let's run the server configured to store data at `./starter.state`. In a terminal session:
Let's run a server configured to store data at `./starter.state`. In a terminal session:
```bash
$ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
......@@ -96,29 +96,61 @@ INFO glngn.server.host.ServerApp$ - application is listening at http://localho
At this point the standalone server is initialized and ready.
See [docs/Deep Dives](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/DeepDives.md)
See [docs/Deep Dives](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/DeepDives.md)
for more details on what happened.
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.
## Examining a Running Server
## Usage
Even in this default configuration the server provides useful routes:
The glngn server provides a REST API with an [OpenAPI](https://www.openapis.org/) specification.
This API supports the built-in features of glngn server as well as any additional features added
by extensions.
### Health Check
If you are looking for a GUI for glngn server [please let us know](mailto:support@dogheadbone.com).
### OpenAPI schema
Let's query for the API schema to see what endpoints there are:
```bash
$ curl http://localhost:10000/openapi.json
{
"openapi" : "3.0.1",
"info" : {
"title" : "dynamic",
"version" : "0.1"
},
"paths": {
"/healthz": ...
"/_ops/groups": ...
[...]
}
}
[...]
```
A brief overview:
1. The `/healthz` route. We'll try that one below.
2. The `/_ops/groups` route. This is an operations route for the groups in glngn server. All services
are placed under a group. The default configuration does not include any groups (or services). This
will be the first route we try in the `API Tour`.
### Multiple Representations
The `/healthz` route will only return status 200 OK if the server is able to handle requests.
This is also a nice example to demonstrate how glngn server supports multiple representations:
```bash
$ curl http://localhost:10000/healthz.txt
OK
```
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.
Worth pointing out that we implicitly requested the text representation of the resource using a `.txt`
suffix. We could have requested another representation, such as json, explicitly or implicitly:
Note the use of a `.txt` extension to request a text representation. We could have
requested another representation, such as `json`, explicitly or implicitly:
```bash
$ curl -H 'Accept: text/plain' localhost:10000/healthz
......@@ -141,38 +173,22 @@ $ curl localhost:10000/healthz.json
This pattern is supported throughout: Endpoints will have suffixed versions that imply the expected
representation.
### OpenAPI schema
Let's query for the API schema to see what other endpoints there are:
```bash
$ curl http://localhost:10000/openapi.json
{
"openapi" : "3.0.1",
"info" : {
"title" : "dynamic",
"version" : "0.1"
},
"paths": {
"/healthz": {
[...]
}
}
[...]
```
Only a few paths are highlighted in the sample output above. Let's touch on those briefly:
1. The `/healthz` route. We've already tried that one
### A Brief Tour
### API Tour
TODO: Go over the general types of default routes)
- `_ops` routes - routes prefixed with a `_`. These are automatically generated.
- All routes prefixed with a `_` are operations routes. These are provided by glngn server.
- `/_ops/`
- Deployment `_ops` routes
- These are always available
- `/_ops/groups`
- query and modify the available groups.
- `/$GROUP/_ops`
- Group `_ops` routes, `/$GROUP/_ops`, require a group to be created
- `/$GROUP/$SERVICE/_ops`
- Service fragment `_ops` routes, `/$GROUP/$SERVICE/_ops`, require the service fragment to be
instantiated under the group.
- automatically generated for each instantiated service fragment
### Groups
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment