# A Step-by-Step introduction to KDK

KDK is mainly powered by the following stack:

If you are not familiar with those technologies and want to develop with the KDK, we first recommend studying how they work. To get a deeper overview of some of the internals we also recommend you to read our technical articles on Medium:

Our main module is simply called kdk (opens new window), available now as a single package @kalisio/kdk (opens new window), but actually composed of two logical parts:

  • core containing basic application services and components
  • map containing required services and components to build geospatial applications

TIP

Although bundled together you can only use the core part without the map part, for instance our application template does not use it. Indeed, on the bakend side related services will not be allocated if the map part is not explicitely used, and on the frontend side Webpack will not bundle unused components.

However, this module also relies on Weacast (opens new window) to manage weather data and feathers-distributed (opens new window) is often used to build microservices architecture, we recommend reading this articles on Medium to get a deeper overview:

WARNING

The KDK was previously available as separated modules like kCore (opens new window)/@kalisio/kdk-core (opens new window), kMap (opens new window)/@kalisio/kdk-map (opens new window), etc. We strongly recommend to upgrade to the latest single package as the features remain similar and development is made easier.

# Application template

A KDK-based application (a.k.a. kApp) usually includes a front-end side client as well as back-end services or an API gateway proxying requests to back-end services. In order to ease the development of new applications we provide you with a KDK application template called the kApp (opens new window) as a starting point. In this guide we will use the template as a reference but most commands will be valid for any KDK-based application.

The kApp includes all the necessary boilerplate that you will need to get started building your application:

It also includes the minimum viable set of features to start:

# Running a kApp from a Docker image

WARNING

This requires you to install Docker (opens new window), the world’s leading software container platform.

Kalisio provides Docker images for the template on the Docker Hub (opens new window) to ease testing it. To run correctly it has to be linked with a standard MongoDB container (opens new window) for the database.

The following commands should do the job:

// Retrieve the latest available dev tag
docker pull kalisio/kapp:0.3.0-dev
// Run the MongoDB container
docker run --name mongodb-kapp -v mongodb_kapp:/data/db -d mongo

// Run the Kalisio app container
docker run --name kapp -d -p 8081:8081 --link mongodb-kapp:mongodb -e "NODE_APP_INSTANCE=" kalisio/kapp:0.3.0-dev

Then point your browser to localhost:8081 (opens new window).

TIP

If running Docker under Windows in a virtual machine first redirect the port 8081 of your virtual machine to your host

You can also use docker-compose (opens new window) and the docker compose files (opens new window). The following commands should do the job:

docker pull kalisio/kapp
// Run the MongoDB and Kalisio app containers
docker-compose up -d

// Stop the MongoDB and Kalisio app containers
docker-compose down
// Stop the MongoDB and Kalisio app containers erasing DB data
docker-compose down -v

TIP

For most applications some secrets (like your AWS S3 access key) need also to be set in your environment to make it work, see deployment prerequisites

# Running a kApp from source code

First you have to ensure you fulfilled the prerequisites to build and run kApp from source code. Then the following commands, assuming you have a MongoDB instance running on local host and default port (27017), should launch your local instance:

// Clone kApp
git clone https://github.com/kalisio/kApp.git
cd kApp

// Client build
yarn install
yarn build

// Server build
cd api
yarn install
yarn build

// Running the server in production will also serve the client
yarn prod

Then point your browser to localhost:8081 (opens new window).

To start coding into your application please refer to our development guide.

# Configuring a kApp

# Backend side

kApp backend configuration is based on Feathers (opens new window) so the same guidelines are applicable, the default configuration can be found in the api/config folder. The main properties are the following:

  • apiPath: the API path prefix
  • port: the server port
  • domain: the web application domain name (eg https://app.kalisio.xyz)
  • apiLimiter: the API rate limiting configuration
  • authentication : object configuring Feathers authentication (opens new window) plus custom options
    • passwordPolicy: password policy configuration
      • minLength: minimum length
      • maxLength: maximum length
      • uppercase: boolean indicating if the password requires at least an uppercase letter
      • lowercase: boolean indicating if the password requires at least an uppercase letter
      • digits: boolean indicating if the password requires at least a digit
      • symbols: boolean indicating if the password requires at least a symbol
      • prohibited: array of prohibited common passwords
      • history: number of passwords to look for in history to avoid keeping a similar one when changing
    • defaultUsers: the array of default users to be created on launch (format { email, password })
      • note: will not be exposed on staging/production environments for security concerns
    • limiter: the authentication API rate limiting configuration
  • logs: object configuring the winston (opens new window) loggers to be used - each key is a transport name (opens new window) which value is associated configuration options
  • db: database configuration
  • storage: storage service configuration used by core
    • accessKeyId: AWS S3 access key
    • secretAccessKey: AWS S3 secret access key
    • bucket: AWS S3 bucket to be used
  • mailer: e-mail service configuration, compliant with nodemailer (opens new window) options plus custom Kalisio options, e.g.
    • service: e-mail service to be used (like gmail)
    • auth: user login and password
    • templateDir: directory containing the e-mails templates to be used
  • pusher: push notification service configuration
    • accessKeyId: AWS SNS access key
    • secretAccessKey: AWS SNS secret access key
    • region: AWS region to be used (like eu-west-1)
    • apiVersion: AWS API version to be used (like 2010-03-31)
    • platforms: object containing as keys platforms names in uppercase (like ANDROID) and corresponding AWS SNS ARN as values
  • proxyTable: a set of proxy rules typically used for scaling

Environment variables (will override defaults in config file):

  • PORT / HTTPS_PORT: backend port for HTTP and HTTPS modes
  • CLIENT_PORT / HTTPS_CLIENT_PORT: frontend port for HTTP and HTTPS modes (only used in development)
  • DB_URL: database URL to access the app database

# Frontend side

kApp frontend configuration is based on the same underlying tool (opens new window) that powers Feathers (opens new window) so the same guidelines are applicable, the default configuration can be found in the config folder. The main properties are the following:

  • apiPath: the API path prefix
  • apiTimeout: the API timeout
  • apiJwt: name of the local storage key used to store the JWT used by the internal API
  • gatewayJwt: name of the local storage key used to store the JWT used by the API gateway
  • version: the web application version number
  • flavor: the web application flavor
  • domain: the web application domain name (eg https://kapp.dev.kalisio.xyz)
  • gateway: the API gateway domain name (eg https://api.dev.kalisio.xyz)
  • transport : the transport to be used between frontend and backend, could be http for standard REST or websocket for WebSockets
  • appName: the name of the app
  • appLogo: the image to be used as logo for the app
  • theme: the theme to be used
  • logs
  • screens: connection screens configuration
    • extraLinks: extra links displayed at the bottom of all screens,
    • banner: displayed application banner,
    • login: login screen configuration
      • providers: array of OAuth2 providers to be used (like ['google', 'github']),
      • links: links displayed at the bottom of the screen,
    • logout: logout screen configuration
      • links: links displayed at the bottom of the screen,
    • changeEndpoint: change endpoint screen configuration (only useful for mobile apps)
      • links: links displayed at the bottom of the screen,
  • layout: layout configuration, see Quasar docs (opens new window) for details
  • myActivity: configuration of the activity named my-activity in the application
    • topPane: application bar components configuration for this activity
      • content: list of components to be displayed according to current mode of the activity (if any),
      • filter: component filter using any expression supported by sift (opens new window),
    • leftPane: left pane (i.e. main menu) components configuration for this activity
      • content: list of components to be displayed according to current mode of the activity (if any),
      • filter: component filter using any expression supported by sift (opens new window),
    • bottomPane: bottom pane components configuration for this activity
      • content: list of components to be displayed according to current mode of the activity (if any),
      • filter: component filter using any expression supported by sift (opens new window),
    • rightPane: right pane components configuration for this activity
      • content: list of components to be displayed according to current mode of the activity (if any),
      • filter: component filter using any expression supported by sift (opens new window),
    • page: additional page components configuration for this activity
      • content: list of components to be displayed according to current mode of the activity (if any),
      • filter: component filter using any expression supported by sift (opens new window),
    • window: window (i.e. widgets) configuration for this activity
      • widgets: list of widgets to be displayed,
      • filter: component filter using any expression supported by sift (opens new window),
    • fab: floating action button (FAB) configuration for this activity
      • actions: list of actions to be displayed,
      • filter: action filter using any expression supported by sift (opens new window)

TIP

The main difference with the backend configuration is that the actual frontend configuration is generated by WebPack at build time from the config files, so you will need to rebuild the app to see your changes applied

WARNING

Althought we use JS objects en environment variables in the frontend configuration to ease writing it please note that the resulting configuration file will be a static JSON file so don't store complex JS objects like functions in the config as it will not work

Environment variables for the frontend development server (will override defaults):

  • PORT / HTTPS_PORT: backend port for HTTP and HTTPS modes (used to configure proxy)
  • CLIENT_PORT / HTTPS_CLIENT_PORT: frontend port for HTTP and HTTPS modes