You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
13
16
14
-
## 0. Why Ferrum
17
+
## 1. Why Ferrum
15
18
16
-
*:white_check_mark: Simple configuration and start
19
+
### 1.1 Main Ferrum advantages:
20
+
*:white_check_mark: Simple configuration and start either as a **native app** or an `docker` containerized app;
17
21
*:sparkles:`Keycloak-compatible API`
18
22
*:boom: Can be **embedded** inside any application or used as a *standalone* application
19
-
*:film_strip: Can be simply install absolutely with no dependent services to single board computer with low resources, requires `40-50 Mb` of `RAM`under low load (10-100 users)
20
-
*:stars: fast (there are no performance test yet, but they will be written during the `0.9.3` version) with aim to be serving up to `10K users on a single node`.
21
-
*:heavy_check_mark:`Ferrum` is widely covered by unit and integration tests every push on `develop` or `master` runs tests and static analyze check with linters.
23
+
*:film_strip: Can be simply install absolutely with no dependent services to single board computer with `low resource usage`, requires `40-50 Mb` of `RAM`with up to `100 - 200 users`;
24
+
*:stars:*fast* (there are no performance test yet, but they will be written during the `0.9.3` version) with aim to be serving up to `10K users on a single node`, `0.9.3.rc1``K6` automated performance tests shows **500 users** simultaneous work with `~20ms 99% of requests` with < `130 Mb of RAM` and `2 CPU Cores` usage;
25
+
*:heavy_check_mark:`Ferrum` is widely covered by unit and integration tests every push on `develop` or `master` runs tests and static analyze check with `linters`.
22
26
*:desktop_computer:`metrics` allow to control all HTTP-requests duration and those part related to data storage access with count three groups by request time - `p50`, `p90` and `p99` also metrics count total amount of requests and errors during requests handling.
23
27
*:microscope: during to modular parts and interface usage, `Ferrum` could be used with any type of persistent storage
First of all build is simple run `go build` from application root directory. Additionally it is possible
62
66
to generate self signed certificates - run `go generate` from command line
@@ -65,7 +69,7 @@ If you don't specify the name of executable (by passing -o {execName} to go buil
65
69
66
70
For running static analyze check use command `golangci-lint run`
67
71
68
-
### 3.2 Run application as Standalone
72
+
### 4.2 Run application as Standalone
69
73
70
74
Run is simple (`Ferrum` starts with default config - `config.json`):
71
75
```ps1
@@ -78,7 +82,7 @@ To run `Ferrum` with selected config i.e. `config_w_redis.json` :
78
82
./Ferrum --config ./config_w_redis.json
79
83
```
80
84
81
-
### 3.3 Run application in docker
85
+
### 4.3 Run application in docker
82
86
83
87
It is possible to start app in docker with already installed `REDIS` and with initial data (see python
84
88
data insert script):
@@ -87,7 +91,7 @@ data insert script):
87
91
docker-compose up --build
88
92
```
89
93
90
-
### 3.4 Run with direct configuration && data pass from code (embedding Authorization server in you applications)
94
+
### 4.4 Run with direct configuration && data pass from code (embedding Authorization server in you applications)
91
95
92
96
There are 2 ways to use `Ferrum`:
93
97
1. Start with config file (described above)
@@ -105,17 +109,33 @@ There are 2 ways to use `Ferrum`:
105
109
app.Stop()
106
110
```
107
111
108
-
### Test
112
+
### 4.5 Testing
113
+
114
+
### 4.5.1 Functional testing
115
+
109
116
At present moment we have 2 fully integration tests, and number of them continues to grow. To run test execute from cmd:
110
117
```ps1
111
118
go test
112
119
```
113
120
For running Manager tests on `Redis` you must have redis on `127.0.0.1:6379` with `ferrum_db` / `FeRRuM000``auth``user+password`
114
121
pair, it is possible to start docker_compose and test on compose `ferrum_db` container
115
122
116
-
## 4. Configure
123
+
### 4.5.2 Performance testing
124
+
Perfomance test running automatically with `K6` included in separate [docker-compose](./docker-compose.perf) running with powershell script - `start_docker_perftests.ps1`. `K6` tests itself located in `tools folder` started with prefix `k6`:
125
+
*`k6_smoke_test.js` - small load with 10 users with 1 min duration;
126
+
*`k6_average_load_test.js` - average load with up to 500 users running ~ `1 hour`
127
+
128
+
Result of running avg load - 10 ms average response time, `p99` (99% of requests) duration around `20 ms`, maximum RAM usage during this test is `130 Mb` and takes `2 CPU Cores`, see results below:
129
+
130
+
@@ -135,7 +155,7 @@ Configuration splitted onto several sections:
135
155
- key file that is using for `JWT` tokens generation (`access_token` && `refresh_token`),
136
156
name `keyfile` (without extensions).
137
157
138
-
### 4.2 Configure user data as you wish
158
+
### 5.2 Configure user data as you wish
139
159
140
160
Users does not have any specific structure, you could add whatever you want, but for compatibility
141
161
with keycloak and for ability to check password minimal user looks like:
@@ -155,7 +175,7 @@ with keycloak and for ability to check password minimal user looks like:
155
175
in this minimal user example you could expand `info` structure as you want, `credentials` is a service structure,
156
176
there are NO SENSES in modifying it.
157
177
158
-
### 4.3 Server embedding into application (use from code)
178
+
### 5.3 Server embedding into application (use from code)
159
179
160
180
Minimal full example of how to use coud be found in `application_test.go`, here is a minimal snippet:
161
181
@@ -195,11 +215,11 @@ if err != nil {
195
215
app.Stop()
196
216
```
197
217
198
-
## 5. Server administer
218
+
## 6. Server administer
199
219
200
220
Since version `0.9.1` it is possible to use `CLI Admin`[See](api/admin/cli/README.md)
201
221
202
-
### 5.1 Use CLI admin in a docker
222
+
### 6.1 Use CLI admin in a docker
203
223
204
224
1. Run docker compose - `docker compose up --build`
205
225
2. List running containers - `docker ps -a`
@@ -208,7 +228,7 @@ Since version `0.9.1` it is possible to use `CLI Admin` [See](api/admin/cli/READ
208
228
209
229
210
230
211
-
### 5.2 Observability (SRE)
231
+
### 6.2 Observability (SRE)
212
232
213
233
For checking application state, we could query the `~/metrics` endpoint (i.e., for local instance full `URL` - `http://127.0.0.1/metrics`). But starting with `0.9.3` were added `prometheus` and `grafana` to be running simultaneously with `Ferrum` using `docker-compose`. `Grafana` model could be found [here](/prometheus/grafana_ferrum_dashboard_model.json). It requires only replacing the Prometheus ID.
214
234
@@ -224,7 +244,7 @@ For checking application state, we could query the `~/metrics` endpoint (i.e., f
0 commit comments