Starting Heimdall - getheimdall/heimdall GitHub Wiki

After completing this tutorial you should be able to:

  • Start Heimdall
  • Create a Environment
  • Create an Api
  • Create a Resource
  • Create a Operation
  • Create a Inteceptor

Keep in mind that you are going to start 3 Spring Boot applications, 1 Database instance, RabbitMq and Redis servers. Make sure you have at least 6 GB RAM available on your machine.

First, clone the project

$ git clone --depth=1 https://github.com/getheimdall/heimdall.git heimdall
$ cd heimdall

Docker mode

Requirements

If you would like to build images yourself (with some changes in the code, for example), you will have to clone all the repository and build the artifacts with Maven. Then, run:

$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

docker-compose.dev.yml inherits docker-compose.yml with the additional possibility to build images locally and expose all containers ports for convenient development.

Access Heimdall on: http://localhost:3000

Developer mode

Requirements

Open your favorite Terminal and run these commands.

To start config:

$ cd /heimdall-config
$ mvn spring-boot:run

To start gateway (requires CONFIG already started):

$ cd /heimdall-gateway
$ mvn spring-boot:run

Third, tab to start API (requires CONFIG already started):

$ cd /heimdall-api
$ mvn spring-boot:run

[optional] To start front-end (requires API already started):

With Yarn:

$ cd /heimdall-frontend
$ yarn
$ yarn run

Without Yarn:

$ cd /heimdall-frontend
$ npm install
$ npm run start

Important endpoints

  • http://localhost:8080 - Gateway
  • http://localhost:8888 - Config
  • http://localhost:9090 - API
  • http://localhost:3000 - Front-end

Notes

All Spring Boot applications require an already running Config Server for startup. However, we can start all the containers simultaneously because of depends_on docker-compose option.

Getting Started

You must follow a specific registration process to create the routing process. This documentation will provide all information needed to complete the process through a step-by-step guide.

Environment

The first verification from Heimdall is the environment linked in the request. For an API be registered, it must have a linked environment. The environment is the heart of the routing, with which Heimdall will identify both the origin and destiny routes. One API can be linked with more than one environment; it is your choice.

The first step before registering an API is to define an environment. To do that, use the menu under Menu -> Environment -> Add to start an environment registration.

API

Once there is a registered environment, it is possible to register an API. For that, use the API menu. During the API's registration process, its identification will be the "basepath." An API is a resource group; this resources can be added after the API registration is finished.

Resources

The resource is nothing more than one operation group. Its use is to organize the operations (that will be explained in the next topic). The resource registration can be initialized after an API is added. The resource was created to organize the operations and make it easier to link the interceptors to a group.

Example: User domain; the resource name will be "users"

  • POST - /basePath/users
  • GET - /basePath/users/{id}
  • PUT - /basePath/users/{id}
  • DELETE - /basePath/users/{id}

A resource can have any name, but to make this example simpler, we will use the names that make sense about the operations used in this documentation.

Operations

It is necessary to add some operations to complete the basic lifecycle to use the API. The operation is a real service the gateway will route. A group of operations comprise an API. They are responsible for mapping the back-end services that will be called. As an example, we used the same paths as in the resources topic.

Example: User domain; the resource name will be "users"

  • POST - /basePath/users
  • GET - /basePath/users/{id}
  • PUT - /basePath/users/{id}
  • DELETE - /basePath/users/{id}

The bolded portions above are operations. An operation needs an HTTP verb to be unique.

Plans

The plan is just a tag to the API. Its main function is to link some resources that Heimdall have without impacting the API directly, making possible for multiple API consumers to have their respective configurations without one affecting the other.

For instance, think of two clients consuming the same API, but one of them wants to save the request logs, and the other does not. To enable this, one client will have a "Plan A," and the other will have a "Plan B," where "Plan A" will be linked with an "Interceptor Log" and "Plan B" will not. This way, both will be consuming the same service without affecting each other.

Interceptors

With Heimdall, you can manipulate the requests through the interceptors. You can intercept requests in lots of situations, like block access to some services or save the request logs. By default, Heimdall already has some interceptors available.

To create an interceptor, an API needs to exist. When you select an API, you can see an "Interceptor" tab to manipulate or add a new interceptor. Using drag n' drop, it is possible to add or remove an interceptor where you wish. Drag an interceptor to the request or response areas, and a dialog will be shown for you to submit an interceptor with its details.

It is important to note that you cannot add an interceptor directly to an API; you can attach it to a Plan, Resource or Operation that are registered to that API.

Developers

Heimdall being an orchestrator, you have lots of managers, and one of their responsibilities is to govern the developers using the API. A developer can use registered apps to consume the API services. To manage the developers, you need to navigate to developers menu; there you can add a new developer or manipulate the registered developers.

Apps

The developer can own multiple apps inside Heimdall. An app represents an external application that the developer wants to register in Heimdall. The app can consume any API registered in Heimdall. Every app created has its own 'Client ID'; this 'Client ID,' in most cases, is used to identify the app in the request.

Access Tokens

'Access tokens' are tokens used to provide basic access through Heimdall. They are linked to an app and, to turn on the validation, it is necessary you add an 'Access Token Interceptor.'

It is important to know that Access Token Interceptor requires a Client ID Interceptor