<commit_before>---
title: Getting Started with Knot.x Stack
description: "In this tutorial, we explain how to start playing with Knot.x using Knotx Stack. We will do similar again Hello Rest Service Tutorial showing how Knot.x can be used to transform a static website into a dynamic one."
author: skejven
keywords: tutorial
order: 7
date: 2018-04-18
knotxVersion: 1.3.0
---
## Overview

We start this tutorial with great news! Finally [Knot.x Stack](https://github.com/Knotx/knotx-stack) is available.

Let's just cut to the point. In this tutorial we will configure Knot.x instance with simple page that
uses external datasource (Google API Books) to fetch the dynamic data and display it on our page.

What you’re going to learn:

- How to setup Knot.x instance using [Knot.x Stack](https://github.com/Knotx/knotx-stack)
- How to transform static HTML into dynamic content and configure Knot.x to use simple REST services to get data
- How to use data from such services to dynamically populate HTML

## Setup bare Knot.x instance

**Prerequisites**
You will need following things to use Knot.x stack:
- JDK 8
- Linux or OSX bash console (for Windows users we recommend using e.g. Ubuntu with [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)).

Download [Knot.x distribution](http://knotx.io/download) and unzip it to any repository.

For the purpose of this tutorial let's call the structure of unzipped stack `KNOTX_HOME`.
`KNOTX_HOME` which is Knot.x instance with configuration and dependencies has following structure:

```
├── bin
│   └── knotx                     // shell script used to resolve and run knotx instance
├── conf                          // contains application and logger configuration files
│   ├── application.conf          // defines all modules that Knot.x instance is running, provides configuration for Knot.x Core and global variables for other config files
│   ├── bootstrap.json            // config retriever options, defines application configuration stores (e.g. points to `application.conf` - the main configuration)
│   ├── default-cluster.xml       // basic configuration of Knot.x instance cluster
│   ├── includes                  // additional modules configuration which are included in `application.conf`
│   │   ├── actionKnot.conf
│   │   ├── hbsKnot.conf
│   │   ├── httpRepo.conf
│   │   ├── server.conf
│   │   ├── serviceAdapter.conf
│   │   └── serviceKnot.conf
│   └── logback.xml          // logger configuration
├── knotx-stack.json         // stack descriptor, defines instance libraries and dependencies
├── lib                      // contains instance libraries and dependencies, instance classpath
│   ├── list of project dependency libraries
│   ├── ...
```

Now, run
```cmd
bin/knotx run-knotx
```
to start Knot.x instance. You should see that instance is running and all its modules are starting:
```
2018-04-17 09:48:39.849 [vert.x-eventloop-thread-0] INFO  i.k.launcher.KnotxStarterVerticle - Knot.x STARTED
      Deployed httpRepo=java:io.knotx.repository.http.HttpRepositoryConnectorVerticle [233dced4-658a-422b-870f-51f12a7ced21]
      Deployed assembler=java:io.knotx.assembler.FragmentAssemblerVerticle [9a075059-4b73-4f50-9890-d38282e2ace4]
      Deployed serviceKnot=java:io.knotx.knot.service.ServiceKnotVerticle [0c5ac5ea-a196-4678-8f11-e6af84f23e7c]
      Deployed splitter=java:io.knotx.splitter.FragmentSplitterVerticle [da1384fb-641a-4835-a313-03ecc1c42458]
      Deployed hbsKnot=java:io.knotx.knot.templating.HandlebarsKnotVerticle [41875d6a-699a-4099-969f-115292152801]
      Deployed serviceAdapter=java:io.knotx.adapter.service.http.HttpServiceAdapterVerticle [ba9429fb-ef52-4241-8c11-94977b0a30c9]
      Deployed server=java:io.knotx.server.KnotxServerVerticle [1d044822-8c95-4ae4-b2f8-6886412400eb]
```

Congratulation! That's it. You have your own bare Knot.x instance running.

## Hello Service configuration
Lets now configure Knot.x to do the magic for us.
We need to do following things:
- provide the page template, for the tutorial purpose we will use `fileSystemRepo`,
- provide the datasource, we will use the Google Books API.

> All configuration options and default values, such as address fields, for each Knot.x module are
described directly in the configuration files of those modules in `conf`.


### Templates repository configuration
By default `fileSystemRepo` is not enabled in Knot.x Stack, because it purposes are purely academical.
It is not designed to be used as production ready solution (you should use `httpRepo` there).
<commit_msg>update getting started tutorial<commit_after>---
title: Getting Started with Knot.x Stack
description: "In this tutorial, we explain how to start playing with Knot.x using Knotx Stack. We will do similar again Hello Rest Service Tutorial showing how Knot.x can be used to transform a static website into a dynamic one."
author: skejven
keywords: tutorial
order: 7
date: 2018-05-18
knotxVersion: 1.3.0
---
## Overview

We start this tutorial with great news! Finally [Knot.x Stack](https://github.com/Knotx/knotx-stack) is available.

Let's just cut to the point. In this tutorial we will configure Knot.x instance with simple page that
uses external datasource (Google API Books) to fetch the dynamic data and display it on our page.

What you’re going to learn:

- How to setup Knot.x instance using [Knot.x Stack](https://github.com/Knotx/knotx-stack)
- How to transform static HTML into dynamic content and configure Knot.x to use simple REST services to get data
- How to use data from such services to dynamically populate HTML

## Setup basic Knot.x instance

**Prerequisites**
You will need following things to use Knot.x stack:
- JDK 8
- Linux or OSX bash console (for Windows users we recommend using e.g. Ubuntu with [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)).

Download [Knot.x distribution](http://knotx.io/download) and unzip it to any repository.

For the purpose of this tutorial let's call the structure of unzipped stack `KNOTX_HOME`.
`KNOTX_HOME` which is Knot.x instance with configuration and dependencies has following structure:

```
├── bin
│   └── knotx                     // shell script used to resolve and run knotx instance
├── conf                          // contains application and logger configuration files
│   ├── application.conf          // defines all modules that Knot.x instance is running, provides configuration for Knot.x Core and global variables for other config files
│   ├── bootstrap.json            // config retriever options, defines application configuration stores (e.g. points to `application.conf` - the main configuration)
│   ├── default-cluster.xml       // basic configuration of Knot.x instance cluster
│   ├── includes                  // additional modules configuration which are included in `application.conf`
│   │   ├── actionKnot.conf
│   │   ├── hbsKnot.conf
│   │   ├── httpRepo.conf
│   │   ├── server.conf
│   │   ├── serviceAdapter.conf
│   │   └── serviceKnot.conf
│   └── logback.xml          // logger configuration
├── knotx-stack.json         // stack descriptor, defines instance libraries and dependencies
├── lib                      // contains instance libraries and dependencies, instance classpath
│   ├── list of project dependency libraries
│   ├── ...
```

Now, run
```cmd
bin/knotx run-knotx
```
to start Knot.x instance. You should see that instance is running and all its modules are starting:
```
2018-04-17 09:48:39.849 [vert.x-eventloop-thread-0] INFO  i.k.launcher.KnotxStarterVerticle - Knot.x STARTED
      Deployed httpRepo=java:io.knotx.repository.http.HttpRepositoryConnectorVerticle [233dced4-658a-422b-870f-51f12a7ced21]
      Deployed assembler=java:io.knotx.assembler.FragmentAssemblerVerticle [9a075059-4b73-4f50-9890-d38282e2ace4]
      Deployed serviceKnot=java:io.knotx.knot.service.ServiceKnotVerticle [0c5ac5ea-a196-4678-8f11-e6af84f23e7c]
      Deployed splitter=java:io.knotx.splitter.FragmentSplitterVerticle [da1384fb-641a-4835-a313-03ecc1c42458]
      Deployed hbsKnot=java:io.knotx.knot.templating.HandlebarsKnotVerticle [41875d6a-699a-4099-969f-115292152801]
      Deployed serviceAdapter=java:io.knotx.adapter.service.http.HttpServiceAdapterVerticle [ba9429fb-ef52-4241-8c11-94977b0a30c9]
      Deployed server=java:io.knotx.server.KnotxServerVerticle [1d044822-8c95-4ae4-b2f8-6886412400eb]
```

Congratulation! That's it. You have your own basic Knot.x instance running.

## Hello Service configuration
Lets now configure Knot.x to do the magic for us.
We need to do following things:
- provide the page template, for the tutorial purpose we will use `fileSystemRepo`,
- provide the datasource, we will use the Google Books API.

> All configuration options and default values, such as address fields, for each Knot.x module are
described directly in the configuration files of those modules in `conf`.


### Templates repository configuration
By default `fileSystemRepo` is not enabled in Knot.x Stack, because it purposes are purely academical.
It is not designed to be used as production ready solution (you should use `httpRepo` there).

{'fraction_non_alphanumeric': 0.0880817746846455, 'fraction_numerical': 0.041757285776424534, 'mean_word_length': 3.7901041666666666, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6342713', 'n_tokens_mistral': 3054, 'n_tokens_neox': 2803, 'n_words': 1035}