|
|
[[_TOC_]]
|
|
|
# Code Structure
|
|
|
|
|
|
The backend part of Stork is written in Go language while the UI is written in Angular. Therefore, we elected to organize the code based on practices for GoLang and Angular apps. This does not preclude adding some code structures written in other programming languages in the future. The best organization will have to be judged on case by case basis.
|
|
|
|
|
|
## Folders
|
|
|
|
|
|
- api - API exposed to users by Stork Server defined using Swagger
|
|
|
- backend - the backend part of Stork, written in GoLang
|
|
|
- backend/api - API exposed by Stork Agents to Stork Server, defined gRPC and protobuf
|
|
|
- backend/agent - source code of STAG (Stork Agent)
|
|
|
- backend/cmd - directories with main functions for Stork Server and Stork Agent binaries
|
|
|
- backend/server - source code of Stork Server
|
|
|
- backend/server/gen - sources generated by goswagger
|
|
|
- docker - docker related files used to start demo
|
|
|
- docs - documentation
|
|
|
- grafana - Grafana template for BIND and Kea
|
|
|
- tools - various tools downloaded by Rake for building and checking the source code
|
|
|
- webui - source code for frontend in Angular
|
|
|
|
|
|
## Files
|
|
|
- docker-compose.yaml - docker-compose file that arranges all services together and allows running whole solution under the desk
|
|
|
- Rakefile - a file with variuos tasks like getting dependencies or building backend and frontend or running docker compose
|
|
|
- README.md
|
|
|
- api/swagger.yaml - REST API definition shared by WebUI and Stork Server
|
|
|
- Vagrantfile - a config for Vagrant that allows bringing up Ubunut 18.04 VM with preinstalled dependencies, ready for doing development
|
|
|
|
|
|
# Dependencies
|
|
|
|
|
|
## Base Dependencies
|
|
|
|
|
|
Ubuntu 18.04 is the main development environment. The base dependencies for building the code are:
|
|
|
- [Rake](https://ruby.github.io/rake/) - a tool for automating taks
|
|
|
- Java Runtime Environment (JRE) - this is used for generating code for web UI based on Swagger, which is part of the build process. Java is a build-time dependency, not a run-time dependency. In other words, *Java is not needed to run Stork*.
|
|
|
- Docker and Docker Compose - used for arranging all the parts into one solution that can be run under the desk, still all the parts can be run directly without Docker. We use docker, because it greatly helps with build automation. *The future Stork releases will not require to use Docker*.
|
|
|
|
|
|
These tools need to be installed manually. The rest of dependencies are fetched by Rake.
|
|
|
|
|
|
## Backend Dependencies
|
|
|
All these dependencies are downloaded by `rake prepare_env`.
|
|
|
|
|
|
- Go 1.13 - for building whole backend
|
|
|
- goswagger.io - for generating backend part of REST API based on Swagger
|
|
|
- golangci-lint - for static analysis of Go source code
|
|
|
|
|
|
## Frontend Dependencies
|
|
|
All these dependencies are downloaded by `rake prepare_env`.
|
|
|
|
|
|
- swagger_codegen.jar - official Swagger code generator in Java used for generating frontend part of REST API
|
|
|
- nodejs & npm - used for getting javascript dependencies for frontend and building it
|
|
|
|
|
|
# Rakefile
|
|
|
|
|
|
Rakefile is located in top folder of Stork repository. The first task that should be invoked for just cloned repository is `prepare_env`:
|
|
|
```console
|
|
|
$ rake prepare_env
|
|
|
```
|
|
|
This task downloads all other dependencies. They are put into `tools` folder.
|
|
|
|
|
|
## Provided Tasks
|
|
|
|
|
|
Rake can display its provided tasks. This can be done using the following commands:
|
|
|
|
|
|
```console
|
|
|
$ rake -T
|
|
|
```
|
|
|
|
|
|
or in more descriptive form:
|
|
|
```console
|
|
|
$ rake -D
|
|
|
```
|
|
|
|
|
|
## Rationale
|
|
|
|
|
|
Rake has been selected as it is more versatile and feature rich task definition tool then popular make. It eliminates many gotchas that one may encounter in make. There are more alternatives to make but rake is one of the most popular.
|
|
|
|
|
|
# Building, Testing and Running Stork
|
|
|
|
|
|
There are several task provided by Rakefile for building and testing source code depending on the part of Stork.
|
|
|
|
|
|
## Backend
|
|
|
|
|
|
Building whole backend:
|
|
|
```console
|
|
|
$ rake build_backend
|
|
|
```
|
|
|
|
|
|
Building the server part:
|
|
|
```console
|
|
|
$ rake build_server
|
|
|
```
|
|
|
Building the agent part:
|
|
|
```console
|
|
|
$ rake build_agent
|
|
|
```
|
|
|
|
|
|
Running unit tests:
|
|
|
```console
|
|
|
$ rake unittest_backend
|
|
|
```
|
|
|
|
|
|
Static analysis:
|
|
|
```console
|
|
|
$ rake lint_go
|
|
|
```
|
|
|
|
|
|
Runnig agent:
|
|
|
```console
|
|
|
$ rake run_agent
|
|
|
```
|
|
|
|
|
|
Runnig server:
|
|
|
```console
|
|
|
$ rake run_server
|
|
|
```
|
|
|
|
|
|
## Frontend
|
|
|
|
|
|
Building:
|
|
|
```console
|
|
|
$ rake build_ui
|
|
|
```
|
|
|
|
|
|
Static analysis:
|
|
|
```console
|
|
|
$ rake lint_ui
|
|
|
```
|
|
|
|
|
|
Starting Angular development server
|
|
|
```console
|
|
|
$ rake serve_ui
|
|
|
```
|
|
|
|
|
|
## Demo
|
|
|
|
|
|
Building and running demo:
|
|
|
```console
|
|
|
$ rake docker_up
|
|
|
```
|
|
|
|
|
|
and now visit in a web browser: http://localhost:8080/ |
|
|
\ No newline at end of file |