137 lines
5.9 KiB
Markdown
137 lines
5.9 KiB
Markdown
# Development
|
|
|
|
## Setup
|
|
|
|
If you haven't installed Go on your system yet, follow the [golang installation guide](https://golang.org/doc/install).
|
|
|
|
To get your local setup going, run `make bootstrap`. It will install all required dependencies as well as setting up our git hooks. Run `make help` to get an overview of available make targets.
|
|
|
|
The project can be compiled using `make build`. This should create a binary which can then be executed.
|
|
|
|
Alternatively, the `go run ./cmd/poseidon` command can be used to automatically compile and run the project.
|
|
|
|
### URLs
|
|
|
|
Once you completed the project setup, you can check the availability using the following URL:
|
|
|
|
```http request
|
|
http://localhost:7200/api/v1/version
|
|
```
|
|
|
|
Using the prefix `/api/v1`, all routes as described in [API documentation](../api/swagger.yaml) are available and thus can be used in conjunction with [CodeOcean](https://github.com/openHPI/codeocean).
|
|
|
|
## Tests
|
|
|
|
As testing framework we use the [testify](https://github.com/stretchr/testify) toolkit.
|
|
|
|
Run `make test` to run the unit tests.
|
|
|
|
### Mocks
|
|
|
|
For mocks we use [mockery](https://github.com/vektra/mockery). You can create a mock for the interface of your choice by running
|
|
|
|
```bash
|
|
make mock name=INTERFACE_NAME pkg=./PATH/TO/PKG
|
|
```
|
|
|
|
on a specific interface.
|
|
|
|
For example, for an interface called `ExecutorApi` in the package `nomad`, you might run
|
|
|
|
```bash
|
|
make mock name=ExecutorApi pkg=./nomad
|
|
```
|
|
|
|
If the interface changes, you can rerun this command (deleting the mock file first to avoid errors may be necessary).
|
|
|
|
Mocks can also be generated by using mockery directly on a specific interface. To do this, first navigate to the package the interface is defined in. Then run
|
|
|
|
```bash
|
|
mockery \
|
|
--name=<<interface_name>> \
|
|
--structname=<<interface_name>>Mock \
|
|
--filename=<<interface_name>>Mock.go \
|
|
--inpackage
|
|
```
|
|
|
|
For example, for an interface called `ExecutorApi` in the package `nomad`, you might run
|
|
|
|
```bash
|
|
mockery \
|
|
--name=ExecutorApi \
|
|
--structname=ExecutorAPIMock \
|
|
--filename=ExecutorAPIMock.go \
|
|
--inpackage
|
|
```
|
|
|
|
Note that per default, the mocks are created in a `mocks` sub-folder. However, in some cases (if the mock implements private interface methods), it needs to be in the same package as the interface it is mocking. The `--inpackage` flag can be used to avoid creating it in a subdirectory.
|
|
|
|
### End-to-end tests
|
|
|
|
For e2e tests we provide a separate package. e2e tests require the connection to a Nomad cluster.
|
|
Run `make e2e-tests` to run the e2e tests. This requires Poseidon to be already running.
|
|
Instead, you can run `make e2e-docker` to run the API in a Docker container, and the e2e tests afterwards.
|
|
You can use the `DOCKER_OPTS` variable to add additional arguments to the Docker run command that runs the API. By default, it is set to `-v $(shell pwd)/configuraton.yaml:/configuration.yaml`, which means, your local configuration file is mapped to the container. If you don't want this, use the following command.
|
|
|
|
```shell
|
|
$ make e2e-docker DOCKER_OPTS=""
|
|
```
|
|
|
|
### Local Nomad
|
|
|
|
In order to support the development of Poseidon, a local Nomad dev server is recommended. Following the instructions below, you can setup a Nomad server on your local system that won't persist any data between restarts. More details can be found on [Nomad's official website](https://www.nomadproject.io/docs/install).
|
|
|
|
#### macOS
|
|
|
|
```shell
|
|
brew tap hashicorp/tap
|
|
brew install hashicorp/tap/nomad
|
|
brew services start nomad
|
|
```
|
|
|
|
**Prerequisites**: [Docker for Mac](https://docs.docker.com/desktop/mac/install/) is installed and started:
|
|
```shell
|
|
brew install --cask docker
|
|
```
|
|
|
|
**Note**: Due to architecture of Docker networking on macOS, the bridge network is not available with Nomad. Please refer to the [Nomad FAQ](https://www.nomadproject.io/docs/faq#q-how-to-connect-to-my-host-network-when-using-docker-desktop-windows-and-macos) for more information. As a result, those environments having network access enabled won't sync properly to Nomad and thus cannot be started.
|
|
|
|
#### Linux
|
|
|
|
```shell
|
|
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
|
|
sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
|
|
sudo apt-get update && sudo apt-get install nomad
|
|
sudo nomad agent -dev
|
|
```
|
|
|
|
#### Namespace registration
|
|
|
|
As the Nomad dev serer does not persist any data, the namespace selected in the configuration of Poseidon needs to be created each time the Nomad server is started. This can be done with the following command:
|
|
|
|
```shell
|
|
nomad namespace apply -description "Poseidon development namespace" poseidon
|
|
```
|
|
|
|
Alternatively, the namespace used by Poseidon can be updated to `default` so that no additional namespace is required.
|
|
|
|
## Coding Style
|
|
|
|
### Git hooks
|
|
|
|
The repository contains a git pre-commit hook which runs the go formatting tool `gofmt` to ensure the code is formatted properly before committing. To enable them, run `make git-hooks`.
|
|
|
|
### Linter
|
|
|
|
To lint our source code and ensure a common code style in the codebase we use [Golang CI Lint](https://golangci-lint.run/usage/install/#local-installation) as a linter. Use `make lint` to execute it.
|
|
|
|
## Continuous Integration
|
|
|
|
We use the Gitlab CI to automatically build the project, run unit and e2e-tests, perform an automated dependency check and deploy instances of the API.
|
|
|
|
### Docker
|
|
|
|
The CI builds a Docker image and pushes it to the Docker registry associated with this repo. Execute `sudo docker run -p 7200:7200 ghcr.io/openhpi/poseidon` to run the image locally. You can find all available images on the [package listing on GitHub](https://github.com/openHPI/poseidon/pkgs/container/poseidon). Once started, you can then interact with the webserver on your local port 7200.
|
|
|
|
You can also build the Docker image locally by executing `make docker` in the root directory of this project. It builds the binary first and a container with the tag `poseidon:latest` afterwards. You can then start a Docker container with `sudo docker run --rm -p 7200:7200 poseidon:latest`.
|