- Code Structure
- Building, Testing and Running Stork
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.
- 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
- docker-compose.yaml - docker-compose file that arranges all services together and allows running whole solution under the desk
- Rakefile - a file with various tasks like getting dependencies or building backend and frontend or running docker compose
- api/swagger.yaml - REST API definition shared by WebUI and Stork Server
- Vagrantfile - a config for Vagrant that allows bringing up Ubuntu 18.04 VM with preinstalled dependencies, ready for doing development
Ubuntu 18.04 is the main development environment. The base dependencies for building the code are:
- 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.
All these dependencies are downloaded by
- 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
All these dependencies are downloaded by
- swagger_codegen.jar - official Swagger code generator in Java used for generating frontend part of REST API
Rakefile is located in top folder of Stork repository. The first task that should be invoked for just cloned repository is
$ rake prepare_env
This task downloads all other dependencies. They are put into
Rake can display its provided tasks. This can be done using the following commands:
$ rake -T
or in more descriptive form:
$ rake -D
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.
Building whole backend:
$ rake build_backend
Building the server part:
$ rake build_server
Building the agent part:
$ rake build_agent
Running unit tests:
$ rake unittest_backend
This requires to have Postgres DB running. A potentially convenient alternative is to run:
$ rake unit_test_backend_db
which will spin up a docker container with a DB and will run unit tests on it.
$ rake lint_go
$ rake run_agent
$ rake run_server
$ rake build_ui
$ rake lint_ui
Starting Angular development server
$ rake serve_ui
Building and running demo:
$ rake docker_up
and now visit in a web browser: http://localhost:8080/
Demo is described here, although the steps description sometimes is outdated.