SkillTree Docs

# Quick Start

The steps to getting started with SkillTree are:

  1. Prerequisites - don't worry there isn't much here
  2. Install and Start the Dashboard and create your project
  3. (Optional) Integrate Client Libraries into your application (examples will be provided)

Please Note

Please note that the integrating the SkillTree Client Library is optional and is only applicable when integrating gamification training directly into an existing or new web application.

# 1. Prerequisites

TIP

If a PosgtgreSQL database is not already available, one can easily be started using a docker container (see example below), or visit the official please documentation https://www.postgresql.org for other installation options.

docker run --network=host -e POSTGRES_USER=skills -e POSTGRES_PASSWORD=skillsPassword -d postgres

# 2. Install & Start Dashboard and Service

You have 2 options:

  • Option 1 - utilize a pre-built docker image
  • Option 2 - download and run the jar-based distribution

# Option 1 - Docker-based install

The skills-service docker image is hosted on DockerHub and can be started like this:

docker run --name skills-service -d -p 8080:8080 -e SPRING_PROPS="\
spring.datasource.url=jdbc:postgresql://localhost:5432/skills,\
spring.datasource.username=skills,\
spring.datasource.password=skillsPassword" skilltree/skills-service:<tag_version>

IMPORTANT

Please note that the latest tag is not published to DockerHub and :<tag_version> must be specified explicitly. Available tags can be found on DockerHub tags page .

You can tail the application logs via:

docker logs -f <container_id>

Your output will look something like this (the majority of the output was omitted for brevity):

 .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (vX.X.X.RELEASE)
...
...
...
2020-07-16 19:43:01.129  INFO 9103 --- [           main] o.s.m.s.b.SimpleBrokerMessageHandler     : Started.
2020-07-16 19:43:01.189  INFO 9103 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2020-07-16 19:43:01.192  INFO 9103 --- [           main] skills.SpringBootApp                     : Started SpringBootApp in 20.159 seconds (JVM running for 21.368)

The dashboard is now running on http://localhost:8080 (opens new window).

Well... that's it!

The next step is to start the java-backend-example service which:

  1. Populates the skills-service with sample data
  2. Implements an example Authentication Endpoint that's required to run client components

Download the latest java-backend-example from skills-client-examples/releases 

curl -s https://api.github.com/repos/NationalSecurityAgency/skills-client-examples/releases/latest | grep browser_download_url | cut -d '"' -f 4 | wget -qi -

Start java-backend-example using the downloaded jar (make sure to substitute X.X.X for an actual version):

java -jar java-backend-example-X.X.X.jar

Please note that java-backend-example populates the skills-service with sample data so it may take few minutes to start. Once sample data population has completed, the following line appears on standard out:

o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8090 (http) with context path ''

On start, java-backend-example populates the skills-service with a sample project named Movies. Once it starts, logout from the dashboard and log back in as

  • username=bill@email.org
  • password=password and explore the sample Movies project.

# Option 2 - Jar-based install

Download the latest .jar release from GitHub skills-service/releases/ (under the Assets section).

curl -s https://api.github.com/repos/NationalSecurityAgency/skills-service/releases/latest | grep browser_download_url | cut -d '"' -f 4 | wget -qi -

Using the downloaded jar you can run the SkillTree dashboard and service (make sure to substitute X.X.X for an actual version):

$ java -Dspring.datasource.url=jdbc:postgresql://localhost:5432/skills \
-Dspring.datasource.username=skills \
-Dspring.datasource.password=skillsPassword \
-jar ~/Downloads/skills-service-X.X.X.jar

Your output will look something like this (the majority of the output was omitted for brevity):

 .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (vX.X.X.RELEASE)
...
...
...
2020-07-16 19:43:01.129  INFO 9103 --- [           main] o.s.m.s.b.SimpleBrokerMessageHandler     : Started.
2020-07-16 19:43:01.189  INFO 9103 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2020-07-16 19:43:01.192  INFO 9103 --- [           main] skills.SpringBootApp                     : Started SpringBootApp in 20.159 seconds (JVM running for 21.368)

The dashboard is now running on http://localhost:8080 (opens new window).

Well... that's it!

The next step is to start the java-backend-example service which:

  1. Populates the skills-service with sample data
  2. Implements an example Authentication Endpoint that's required to run client components

Download the latest java-backend-example from skills-client-examples/releases 

curl -s https://api.github.com/repos/NationalSecurityAgency/skills-client-examples/releases/latest | grep browser_download_url | cut -d '"' -f 4 | wget -qi -

Start java-backend-example using the downloaded jar (make sure to substitute X.X.X for an actual version):

java -jar java-backend-example-X.X.X.jar

Please note that java-backend-example populates the skills-service with sample data so it may take few minutes to start. Once sample data population has completed, the following line appears on standard out:

o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8090 (http) with context path ''

On start, java-backend-example populates the skills-service with a sample project named Movies. Once it starts, logout from the dashboard and log back in as

  • username=bill@email.org
  • password=password and explore the sample Movies project.

# 3. Integrate Client Libraries

Please Note

Please note that integrating the SkillTree Client Libraries is optional and is only applicable when integrating gamification training directly into an existing or new web application.

This section assumes that you already have running

  • skills-service on port 8080
  • java-backend-example on port 8090

# Client App Integration Example

To run the Hello World example, clone the skills-client-examples project and start the live-server development server:

git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/js-example
npm install
npm run serve
live-server displays the development server url at startup, it will likely be this:

http://127.0.0.1:8092 (opens new window)

If you want to build the Hello World client integration application yourself, here are the steps:

mkdir js-example
cd js-example
npm init
# accept defaults
npm install --save-dev live-server

You can install the SkillTree JS lib using npm:

npm install @skilltree/skills-client-js --save

However, these examples will utilize <script> tags to import the SkillTree library:

<script type="module">
    import {
        SkillsConfiguration,
        SkillsDisplayJS,
        SkillsReporter
    } from 'https://unpkg.com/@skilltree/skills-client-js/dist/skills-client-js.esm.min.js'

// Use imported components
// ...
</script>

Configure the SkillTree client library - this only needs to happen once per user session:

SkillsConfiguration.configure({
    serviceUrl: 'http://localhost:8080',
    projectId: 'movies',
    authenticator: 'http://localhost:8090/api/users/user4@email.com/token',
});

TIP

In a production environment we'd configure these resources using the https protocol. Please review the Authentication and Configuration sections for greater detail.

Pluggable user skill and ranking visualization:

const clientDisplay = new SkillsDisplayJS({version: 1});
clientDisplay.attachTo(document.querySelector('#skills-client-container'));

Report Skill Events when a user performs actions in the application:

document.querySelector('#reportSkillButton').onclick = function () {
    SkillsReporter.reportSkill('IronMan');
};

Handle event reporting results in one place:

// just so we can always see the response
SkillsReporter.configure({notifyIfSkillNotApplied: true});
SkillsReporter.addSuccessHandler((result) => {
    document.querySelector('#reportResultContainer').innerHTML = JSON.stringify(result, null, ' ');
});

The full example can be found @ skills-client-examples/js-example/index.html

Now start the server:

npx live-server --no-browser --port=8092 --open=app --cors --proxy=/api:http://localhost:8090/api --proxy=/native:http://localhost:8092/
live-server displays development server url on startup, it will likely be this:

http://127.0.0.1:8092 (opens new window).

For further details regarding integrating SkillTree into your application, please visit our Integration Guide.

Last Updated: 11/3/2023, 11:47:32 AM