Helicon

Ahoj, this is the backend of Markus Nentwich shopping system. It provides the ability to manage and order his scores with the typical needings of a shopping system. The main features are:

• order scores

• shopping cart

• product management

• administration

• email notifications

• printable bills

Installation

To perform a plain and direct install, only Git, a Java SDK and an internet connection are required. When these requirements are fulfilled, only a handful of commands need to be entered:

git clone https://github.com/mknentwich/helicon.git
./gradlew bootRun

This may take a while, but when done, the service will listen on the preconfigured port.

ℹ️	The IDE may provide an easier way to start the application for development purposes.

Docker

In order to build a docker image, a docker daemon must be running. An image can be built either using a local gradle instance or using a multistage build with an included gradle instance.

Multistage Build

This is the recommended way for production images, but the build process may take much longer and subsequent builds cannot be performed:

docker build -t dev/helicon:SNAPSHOT-0.0.1 .

Local Build

Almost the same, although the project must be built before:

./gradlew buildJar
docker build -t dev/helicon:SNAPSHOT-0.0.1 -f Dockerfile-single .

ℹ️	The build task buildJar is used here instead of bootJar which is normally used for Spring Boot Applications. This is because the images contain an exploded jar instead of a single jar file.

Run the image

For a successful instance, some resources such as a valid application.yml and an asset directory have to be provided:

docker run -p 2812:2812 -v "$PWD/assets":/assets -v "$PWD/src/main/resources/application.dev.yml":/application.yml --name helicon-dev --rm dev/helicon:SNAPSHOT-0.0.1

💡	You may want to use the same timezone and time as on the host which can be achieved with the volumes -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone

ℹ️	The included application.dev.yml is optimized for a development environment. For example email notifications are disabled and H2 is used instead of Postgres.

Development

To begin development some steps may be necessary.

Lint

To lint the project manually run ./gradlew ktlintFormat. To format the project before every commit run ./gradlew addKtlintFormatGitPreCommitHook once.

Configuration

For development purposes the configuration file is located at src/main/resources/application.yml. In order to provide to the IDE the ability to recognize all available properties and the documentation, gradle kaptKotlin may be run. This is required, everytime the structure of the HeliconConfigurationProperties changes.

💡	To receive an attribute description, refer either to your IDEs autocomplete feature or to src/main/kotlin/at/markusnentwich/helicon/configuration/HeliconConfigurationProperties.kt.

Testing

The main testing strategy in this project are blackbox test. In order to perform them one just run the postman collection helicon-test.postman_collection.json which can be found in the postman directory. If one is running the Helicon instance on localhost with the provided default spring configuration the environment local-test.postman_environment.json can be used.

To perform a quick test newman can be used:

newman run -e postman/local-test.postman_environment.json postman/helicon-test.postman_collection.json

ℹ️	This only works if the newman binary is in the path.

Installing Newman

For the installation either npm or yarn must be installed, as the frontend of this project uses yarn, it will be used in this example.

yarn global add newman

ℹ️	If the npm binary directory is not in the path, one has to run all newman commands with ~/.npm/bin/newman. Alternatively this directory can be added to the path environment variable.

Alternatively, the collection and the environment can be imported into postman and can be used there through the “Runner”. Please take care when writing requests in postman which involve external files, that the paths have to changed to the projects relative after export.

Deployment

As the installation only provides a way for testing, it has to be clarified how to deploy this application. In common environments this will be done via docker so have to refer to the docker compose repository.

Is the REST API documented?

Of course, it is, zum Kuckuck! It can be accessed via http://localhost:2812/api/v1/swagger.html when the application is running. This is enabled by default, if one wants to disable this in production environments, which is not recommend although as in the projects opinion APIs have to be documented publicly, see the configuration section.

Where does the name come from?

This application provides a basis for Markus Nentwich. As he is a musician what would better fit than a helicon?

Minimal Implementation

POST /orders/
PUT /orders/confirmations/{id}
GET /assets/scores/{id}/audio
GET /assets/scores/{id}/pdf
GET /meta/states/{id}
GET /meta/states/
GET /meta/zones/
GET /meta/zones/{id}
GET /catalogue/
GET /catalogue/categories/{id}
GET /catalogue/scores/{id}