# Quick Start
The steps to getting started with SkillTree are:
- Prerequisites - don't worry there isn't much here
- Install and Start the Dashboard and create your project
- Integrate Client Libraries into your application (examples will be provided)
# 1. Prerequisites
- JDK 11+, we suggest Open JDK
- Please note that this is not relevant if you elect to go with the Docker based install.
- Git version 2.23+
- Node.js v12+ and npm 6+
# 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 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 <external-url label="DockerHub tags page" url="https://hub.docker.com/r/skilltree/skills-service/tags".
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!
Good to Know!
Please note that the skills-service
, by default, stores its data into an embedded in-memory H2 database.
That data is ephemeral and will not persist between application restarts. While this is a great way to get started quickly,
it is obviously not appropriate for a test or production installation.
Please visit the Database Section to learn more.
The next step is to start the java-backend-example
service which:
- Populates the
skills-service
with sample data - 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 -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!
Good to Know!
Please note that the skills-service
, by default, stores its data into an embedded in-memory H2 database.
That data is ephemeral and will not persist between application restarts. While this is a great way to get started quickly,
it is obviously not appropriate for a test or production installation.
Please visit the Database Section to learn more.
The next step is to start the java-backend-example
service which:
- Populates the
skills-service
with sample data - 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
This section assumes that you already have running
skills-service
on port8080
java-backend-example
on port8090
Below are the directions for each supported library, please proceed to one of your liking:
- Option 1 - Vue.js Example
- Option 2 - React Example
- Option 3 - Angular Example
- Option 4 - Pure JS Example
# Option 1 - Vue.js Example
To run the Hello World Vue.js example, clone the skills-client-examples
project and start the Vue development server:
git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/vuejs-example
npm install
npm run serve
Vue CLI displays the development server url at startup, it will likely be this: http://localhost:8081/ (opens new window)
If you want to build the Hello World Vue.js application yourself, here are the steps:
TIP
This example uses Vue CLI to quickly scaffold a Single Page Application.
npm install -g @vue/cli
vue create vuejs-example
# accept all of the defaults, press enter
cd vuejs-example
npm run serve
Feel free to check out the Vue.js splash page then kill the server. Let's install and use some of the SkillTree components.
npm install --save @skilltree/skills-client-vue
Configure SkillTree:
main.js
import Vue from 'vue'
import App from './App.vue'
import { SkillsDirective, SkillsConfiguration } from '@skilltree/skills-client-vue';
Vue.config.productionTip = false
Vue.use(SkillsDirective);
SkillsConfiguration.configure({
serviceUrl: 'http://localhost:8080',
projectId: 'movies',
authenticator: 'http://localhost:8090/api/users/user4@email.com/token',
});
new Vue({
render: h => h(App),
}).$mount('#app')
TIP
In a production environment we'd configure these resources using the https
protocol.
Please review the Authentication and Configuration sections for greater detail.
Copy the HelloWorld components from skills-client-examples/vuejs-example/src/components
:
HelloWorldSkillsDisplay.vue
- Pluggable user skill and ranking visualizationHelloWorldSkillsEventReporting.vue
- Report Skill Events when user preforms actions in the applicationHelloWorldGlobalEventHandler.vue
- Handle event reporting results in one place
Now you can use these components in App.vue
:
<template>
<div>
<h1>Current User's Skills Display</h1>
<hello-world-skills-display/>
<h1>Report Skill Events</h1>
<hello-world-skills-event-reporting/>
<h3>Result:</h3>
<hello-world-global-event-handler/>
</div>
</template>
<script>
import HelloWorldSkillsDisplay from "./components/HelloWorldSkillsDisplay";
import HelloWorldSkillsEventReporting from "./components/HelloWorldSkillsEventReporting";
import HelloWorldGlobalEventHandler from "./components/HelloWorldGlobalEventHandler";
export default {
name: 'App',
components: {
HelloWorldGlobalEventHandler,
HelloWorldSkillsEventReporting,
HelloWorldSkillsDisplay,
}
}
</script>
<style>
body {
margin: 0px;
padding-bottom: 3rem;
text-align: center;
}
</style>
For further details regarding integrating SkillTree into your application, please visit our Integration Guide.
# Option 2 - React Integration Example
To run the Hello World React example clone the skills-client-examples
project and start the React development server:
git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/react-example
npm install
npm run start
React CLI displays the development server url at startup, it will likely be this: http://localhost:3000 (opens new window)
If you want to build the Hello World React application yourself, here are the steps:
TIP
This example uses Create React App to quickly scaffold a Single Page Application.
npm install -g create-react-app
create-react-app react-example
cd react-example
npm run start
Feel free to check out the React splash page then kill the server. Let's install and use some of the SkillTree components.
npm install --save @skilltree/skills-client-react
Configure SkillTree:
index.js
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';
import { SkillsConfiguration } from '@skilltree/skills-client-react';
SkillsConfiguration.configure({
serviceUrl: 'http://localhost:8080',
projectId: 'movies',
authenticator: 'http://localhost:8090/api/users/user4@email.com/token',
});
ReactDOM.render(
<React.StrictMode>
<App />
</React.StrictMode>,
document.getElementById('root')
);
serviceWorker.unregister();
TIP
In a production environment we'd configure these resources using the https
protocol.
Please review the Authentication and Configuration sections for greater detail.
Copy the HelloWorld components from skills-client-examples/react-example/src/skilltree
:
HelloWorldSkillsDisplay.js
- Pluggable user skill and ranking visualizationHelloWorldSkillsEventReporting.js
- Report Skill Events when user preforms actions in the applicationHelloWorldGlobalEventHandler.js
- Handle event reporting results in one place
Now you can use these components in App.js
:
import React from 'react';
import './App.css';
import HelloWorldSkillsDisplay from './HelloWorldSkillsDisplay';
import HelloWorldSkillsEventReporting from './HelloWorldSkillsEventReporting';
import HelloWorldGlobalEventHandler from './HelloWorldGlobalEventHandler';
function App() {
return (
<div className="App">
<h1>Current User's Skills Display</h1>
<HelloWorldSkillsDisplay />
<h1>Report Skill Events</h1>
<HelloWorldSkillsEventReporting />
<h3>Result:</h3>
<HelloWorldGlobalEventHandler />
</div>
);
}
export default App;
For further details regarding integrating SkillTree into your application, please visit our Integration Guide.
# Option 3 - Angular Integration Example
To run the Hello World Angular example, clone the skills-client-examples
project and start the Angular development server:
git clone git@github.com:NationalSecurityAgency/skills-client-examples.git
cd skills-client-examples/ng-example
npm install
npm run serve
Angular CLI displays the development server url at startup, it will likely be this: http://localhost:4200/ (opens new window)
If you want to build the Hello World Angular application yourself, here are the steps:
TIP
This example uses Angular CLI to quickly scaffold a Single Page Application.
npm install -g @angular/cli
ng new ng-example
# accept all of the defaults, press enter
cd ng-example
npm run start
Feel free to check out the Angular splash page then kill the server. Let's install and use some of the SkillTree components.
npm install --save @skilltree/skills-client-ng
Configure SkillTree:
main.ts
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { SkillsConfiguration } from '@skilltree/skills-client-ng';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
if (environment.production) {
enableProdMode();
}
SkillsConfiguration.configure({
serviceUrl: 'http://localhost:8080',
projectId: 'movies',
authenticator: 'http://localhost:8090/api/users/user4@email.com/token',
});
platformBrowserDynamic().bootstrapModule(AppModule)
.catch(err => console.error(err));
TIP
In a production environment we'd configure these resources using the https
protocol.
Please review the Authentication and Configuration sections for greater detail.
Copy the HelloWorld components from skills-client-examples/ng-example/src/app/components/*/*.ts
to src/app/
:
hello-world-skills-display.component.ts
- Pluggable user skill and ranking visualizationhello-world-event-reporting.component.ts
- Report Skill Events when user preforms actions in the applicationhello-world-global-event-reporting.component.ts
- Handle event reporting results in one place
Now you can import and declare the components in app.module.ts
:
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { SkillsLevelModule, SkillsDisplayModule, SkilltreeModule } from '@skilltree/skills-client-ng'
import { AppComponent } from './app.component';
import { HelloWorldGlobalEventHandlerComponent } from './hello-world-global-event-handler.component';
import { HelloWorldSkillsDisplayComponent } from './hello-world-skills-display.component';
import { HelloWorldEventReportingComponent } from './hello-world-event-reporting.component';
@NgModule({
declarations: [
AppComponent,
HelloWorldGlobalEventHandlerComponent,
HelloWorldSkillsDisplayComponent,
HelloWorldEventReportingComponent
],
imports: [
BrowserModule,
SkillsLevelModule,
SkilltreeModule,
SkillsDisplayModule,
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
...and use the components in app.component.ts
:
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template: `
<div>
<div>
<h1>Current User's Skills Display</h1>
<app-hello-world-skills-display></app-hello-world-skills-display>
<h1>Report Skill Events</h1>
<app-hello-world-event-reporting></app-hello-world-event-reporting>
<h3>Result:</h3>
<app-hello-world-global-event-handler></app-hello-world-global-event-handler>
</div>
</div>
`,
styles: [`
pre {
margin: auto;
padding: 1rem;
border: 1px solid #dddddd !important;
overflow: auto;
border-radius: 6px;
background-color: #f6f8fa;
min-height: 3rem;
max-width: 80rem;
}
.res {
text-align: left;
}
`]
})
export class AppComponent {
title = 'ng-example';
}
For further details regarding integrating SkillTree into your application, please visit our Integration Guide.
# Option 4 - Pure JS Integration Example
To run the Hello World Pure JS 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
http://127.0.0.1:8092 (opens new window)
If you want to build the Hello World Pure JS 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/
http://127.0.0.1:8092 (opens new window).
For further details regarding integrating SkillTree into your application, please visit our Integration Guide.