BadgeKit Self Hosting Guide

To use BadgeKit, you can build your own BadgeKit instance using the code repos from GitHub. In this guide we will work through the process of building a BadgeKit instance to host on your own server. You may wish to start by building a local instance to acquaint yourself with the setup, pushing to the Web later.

The BadgeKit API and Web app provide back-end badge issuing management - you can complement BadgeKit with your own front-end site for earners. BadgeKit does not handle any of the earner interaction, leaving this to issuers - to make sure you have control over the data for, and interaction with, your own community of earners. For this reason, when you use BadgeKit to "issue" a badge, by default no interaction with the earner will take place automatically. Instead, you can plug into BadgeKit API to detect issuing (and other events), communicating with the earner via your own site.

Before you Start

The BadgeKit tools use node.js, so if you have never used it before you might want to read up at least on the basics - don't worry if you're new to node.js, you really don't need to know much about it to get BadgeKit up and running. To try it out, you can set up a free account on Heroku and create the "Hello World" app in this tutorial, which introduces you to some of the other utilities we will use in this guide, as well as getting them set up on your local environment. These utilities include express, npm and foreman (included in the Heroku Toolbelt).

The bulk of the instructions below are on building a local instance, with notes throughout on additional steps to take if you are pushing to Heroku.

The BadgeKit repos are hosted on GitHub, and the instructions below outline using Git to clone them, so if you have no experience using Git or GitHub, you may also want to read up on it. Again, you won't need advanced knowledge to get BadgeKit set up - working through the GitHub bootcamp tutorials is a great way to start.

Other than that you should be able to follow this guide as long as you have basic terminal/ command line skills and a little MySQL (which we will be using for data storage).

Clone the Repos

Let's get started! Create a directory on your computer for your BadgeKit instance. Open a command prompt/ terminal and navigate to the new directory. We will be using the following repos:

BadgeKit is the Web app which allows issuers to create and manage badges. The BadgeKit API manages badge data and provides access to it - you can use the API to build front-end sites for badge earners.

Note: You can use the BadgeKit API without BadgeKit, but BadgeKit needs the API in order to function - BadgeKit itself doesn't store the data for active badges, this is all handled by the BadgeKit API.

Clone the BadgeKit API repo into your new directory using:

git clone https://github.com/mozilla/badgekit-api.git

This will copy the repo into your directory. Do the same for the BadgeKit repo:

git clone https://github.com/mozilla/openbadges-badgekit.git

You will see that your new directory now contains two folders for the two repos - we will be using some of the files in the repos, and adding to them, as we go.

If you're using Heroku, you can use the following technique:

Log into Heroku in your terminal.

Clone the repos.

Navigate to each repo directory in turn and enter heroku create.

You should see something like this:

> Creating app-name-1111... done, stack is...
> http://app-name-1111.herokuapp.com/ | git@heroku.com:app-name-1111.git
> Git remote heroku added

Heroku will then manage pushing from your repo directories straight to the corresponding remote apps.

If you would like to understand more about how the BadgeKit tools were developed, check out the Twelve Factor App, which will explain some of the decisions the team made during development.

Set Up BadgeKit API

Let's get the BadgeKit API set up first. Navigate to the badgekit-api directory in your terminal. The utility has a set of dependencies you will need to install - use the following command:

npm install

You should see the dependencies being installed - if you encounter any errors you will need to address them before you can continue. You can see the dependencies in the package.json file in the badgekit-api directory.

BadgeKit API Configuration

We need to set up some environment variables for the API. You can do this using an ".env" file if you're starting the application with foreman, or with another file you use with the source command. For example, using the source approach, you could create a file in your badgekit-api directory, naming it something like "env_local" and entering the variables as follows:

export DB_HOST=localhost
export DB_NAME=badgekitapi
export DB_PASSWORD=yourpassword
export DB_USER=root
export MASTER_SECRET=yoursecret
export PORT=8080

This would be a typical setup for a local instance - alter the database name if you like, set your own local MySQL database username/ password and choose a secret. You will need to use the same secret later when we set up the BadgeKit app - the API and BadgeKit each have their own database, so we use a shared secret for authentication, digitally signing requests between the two parts of the application. You will also need to specify the port number for the API when we set up BadgeKit.

When you run the API, or the database migration script, you would use this command first:

source env_local

If you're using foreman, your ".env" file does not need the export syntax, just the variable names and values.

The configs are documented in the BadgeKit API GitHub repo.

You will need to choose a strategy for passing your config details into a remote app. For example, on Heroku you can pass each variable in via the terminal as follows:

heroku config:set DB_HOST=host.cleardb.net

See the Heroku Configuration guide for more details.

BadgeKit API Database

Now we can create the BadgeKit API database. You will need your login details for MySQL - use them in the following command:

mysql --user=root --password=pwd

This would apply to the root user if you are testing locally - replace "root" with a username you use for MySQL access and replace "pwd" with your MySQL password for the specified user.

Your system should start MySQL. You can then create the new database (or use an existing database) using the following:

CREATE DATABASE badgekitapi;

Give the database the name you set in your config file.

In your badgekit-api directory you will see the migration script in the bin directory. After sourcing your config file, run it as follows:

bin/db-migrate up

The script should add the necessary tables to the database you created.

If you use ClearDB on Heroku, you can get the databases for BadgeKit and BadgeKit API setup using virtually the same commands as a local setup. Add ClearDB to each app by running the following from its directory (you can do the same for openbadges-badgekit when you're setting it up later):

heroku addons:add cleardb

When the database has been added, if you then run:

heroku config

You should see the database details in this format:

CLEARDB_DATABASE_URL: mysql://username:password@host.cleardb.net/heroku_db?reconnect=true

You can retrieve the database host, name, username and password from this, or can access them via your Heroku dashboard (by navigating to the app, then selecting the ClearDB addon and choosing the Endpoint Information tab). You can then add the details of your remote database to your config file, running the migration script in the same way as for a local setup.

Once the SQL executes, you should be able to check your database content as follows, while logged into MySQL:

show tables;

You should see the tables listed.

Before we finish with the database, we need to add something to the systems table. BadgeKit needs at least one system to work with, so insert it now using the following structure:

INSERT INTO systems (slug, name, url) VALUES ('badgekit', 'Your System', 'http://localhost:3000');

Replace the values for name and URL - the name should be your main badge issuing system name, which may be the name of your organization. For an overview of how BadgeKit models the issuing bodies in a badging application, see the Glossary. You can now exit from the database:

exit;

Running BadgeKit API

You should now be ready to run your BadgeKit API, as follows for foreman:

foreman start

If you are not using the Heroku Toolbelt, (node) foreman may be addressed differently:

nf start

and

node app

also would do.

You should see an indicator that looks something like this (for running locally):

12:07:01 web.1  | started with pid 3972
12:07:05 web.1  | badgekit-api listening at http://0.0.0.0:8080

You can now open a Web browser and navigate to the address your BadgeKit API is running at:

BadgeKit API Running

If you see something like this - good news! BadgeKit API is running.

For Heroku, you can use Git to push your code to the remote server as follows:

git add .

git commit -m "message"

git push heroku master

Then you can open the app using:

heroku open

If you plan on using the BadgeKit API without the Web app, see the Using BadgeKit API tutorial.

Set Up BadgeKit

Now that BadgeKit API is up and running you can get the BadgeKit app set up. Back in your terminal/ command prompt, navigate to the directory for the openbadges-badgekit repo, which should be in the same directory as the badgekit-api repo if you cloned them in the same place - you may find it easier to open a second terminal window/ tab for BadgeKit, keeping the API in one and the app in another.

BadgeKit Config

Let's start by setting the config details for when BadgeKit runs - we can do this either by creating a config.json file or by setting environment variables (you could alternatively pass them in on the command line when you start the app). You can see more details on the configuration in the BadgeKit repo. You should choose a config option that suits your needs and environment - the following demonstrates preparing the variables in a file that you source before running, for example named "env_local", saved in the root openbadges-badgekit directory:

export COOKIE_SECRET=agoodsecret
export PORT=3000
export OPENBADGER_SYSTEM=badgekit
export OPENBADGER_URL=http://localhost:8080
export OPENBADGER_SECRET=yoursecret
export DATABASE_DRIVER=mysql
export DATABASE_HOST=localhost
export DATABASE_USER=root
export DATABASE_PASSWORD=yourpassword
export DATABASE_DATABASE=badgekit
export PERSONA_AUDIENCE=http://localhost:3000
export API_SECRET=jj54a590432qjj
export BRANDING=abc
export ACCESS_LIST=[\"\^you@yourdomain.com\$\"]

This would reflect a local instance of BadgeKit.

Choose a secret for the COOKIE_SECRET, which will facilitate authentication between the end user and BadgeKit. This will be used for encrypting data in the user client, so should be kept secure. In the client there will be a cookie storing encrypted data - the secret will let the server encrypt the data securely.
OPENBADGER is a legacy term for BadgeKit, so we let the instance know we are using BadgeKit rather than the legacy API in OPENBADGER_SYSTEM. Set the OPENBADGER_URL to the URL your BadgeKit API is running on. The OPENBADGER_SECRET should match the MASTER_SECRET you set in your BadgeKit API instance.
Set the database username and password to match yours - we will be creating the database soon, so choose the name you want to use for it and set it as DATABASE_DATABASE.
BadgeKit uses Persona to manage user account login, for security you need to set the URL that your BadgeKit app is going to run on as PERSONA_AUDIENCE.
API_SECRET should be a random string. This is a shared secret used to add or delete Badgekit users without having to log into the site (see the User API for more info).
BRANDING is an optional short string you can use to add branding to badge ribbons in the visual design tool.
In the ACCESS_LIST array you can use regular expressions to set email addresses for users who will be able to login as soon as the app runs. You may need to alter the use of escape characters in the email address regular expression array for your system to parse it reliably. The access list is primarily useful for development and testing - you can set up user accounts using the database.

Once you have your environment variables set in the file, you can source it as follows in your terminal:

source env_local

The configs will now be used when you run BadgeKit - you will need to do this whenever you run the app locally. To set your app configuration with a config.json file instead of environment variables, you can use the following structure:

{
	"COOKIE_SECRET": "agoodsecret",
	"PORT": "3000",
	"OPENBADGER_SYSTEM": "badgekit",
	"OPENBADGER_URL": "http://localhost:8080",
	"OPENBADGER_SECRET": "yoursecret",
	"DATABASE_DRIVER": "mysql",
	"DATABASE_HOST": "localhost",
	"DATABASE_USER": "root",
	"DATABASE_PASSWORD": "yourpassword",
	"DATABASE_DATABASE": "badgekit",
	"PERSONA_AUDIENCE": "http://localhost:3000",
	"API_SECRET": "jj54a590432qjj",
	"BRANDING": "abc",
	"ACCESS_LIST": ["^you@yourdomain.com$"]
}

Alter the values to suit your own setup and save the file in the root of your openbadges-badgekit directory - the app will automatically attempt to read from it when it runs.

Again, you will need to decide how best to set your config for a remote app - you can use the same techniques outlined above for Heroku:

heroku config:set COOKIE_SECRET=agoodsecret

For each variable, or:

heroku config:push

To push the content of a local environment file.

BadgeKit Dependencies

Now install the dependencies as we did with the BadgeKit API:

npm install

Your dependencies should install - again, if you encounter any errors you will need to address them before continuing.

BadgeKit Database

The BadgeKit app itself also has a database, so let's create it now - remember that we set the database name when we defined the config/ environment variables. Log into MySQL with your own username and password:

mysql --user=root --password=pwd

Create the database:

CREATE DATABASE badgekit;

The name should match what you set in the config. Tell your system to use this new database:

use badgekit

Exit from the database for now:

exit;

Now we can use the migration script as we did with the API:

bin/db-migrate up

You can also see db-migrate in the openbadges-badgekit bin directory, so should be able to run this command from the app's root directory. Your system should now make the necessary changes to get the database set up. You can check by going back into MySQL and running:

show tables;

You can use the same technique for pushing to Heroku as outlined in the BadgeKit API section, adding ClearDB in your openbadges-badgekit directory, retrieving the database URL and using the host, database name, username and password in your config before migrating the data.

Running BadgeKit

You should now be able to start BadgeKit:

foreman start

You should again see an indicator of the location the app is at - open BadgeKit in the browser using the URL and port number:

BadgeKit Running

If you see this BadgeKit is running! For testing, log in using an address that matches what you set in your access list variable.

You can again open the BadgeKit app on Heroku using the following:

heroku open

On logging in, you should be presented with the BadgeKit directory:

BadgeKit Directory

Initially your BadgeKit instance will naturally be empty, but you should be able to create templates and badges, publishing and archiving them. The Applications functionality is still under development.

Tip: If your BadgeKit instance fails when you attempt to publish a badge or to view published/ archived badges, it is likely that BadgeKit and your BadgeKit API instance are not communicating correctly. Make sure the BadgeKit API is running when you run BadgeKit and ensure your shared secret matches in both configs (MASTER_SECRET in the API and OPENBADGER_SECRET in BadgeKit).

You may find it helpful to run a local instance of BadgeKit from one directory, with another in which your badgekit-api and openbadges-badgekit configs are set up for pushing to a remote server.

If you missed the tech panel on installing BadgeKit, you can see the video:

The etherpad also contains answers to some questions people asked during the panel.

Keeping your BadgeKit Instance Updated

Cloning the BadgeKit tools from GitHub gives you a straightforward way to keep your instance updated. To update a local clone of either the BadgeKit API or the app, open a terminal and navigate to the directory storing the local copy (where you cloned to originally - badgekit-api or openbadges-badgekit). You can see if any new changes are available using:

git remote show origin

Your terminal should show you the master branch (as well as other existing branches) with an overview of whether your local copy is up to date. If there are new changes, you can pull them using:

git pull origin master

Git will attempt to merge the changes with your local copy - you should see a rundown of the files changed as Git pulls them. If you experience conflicts merging with your local instance (for example if you have made changes to your local copy, which conflict with the updated version), you can call git merge --abort to return to your local version as it was before you attempted to pull. As an alternative to pull, you can use fetch to retrieve the latest code from GitHub without automatically merging with your local instance - you can then merge manually when you're ready.

When you pull recent changes, it's worth checking for any corresponding changes to the docs (for example new information in the readme file), in case you need to take steps to keep your version of BadgeKit functional. You can also use the GitHub repo (including the wiki) to see any changes to our guidance on using BadgeKit, in case it relates to differences or additions you are pulling into your instance. If you watch the BadgeKit repos on GitHub, you will receive notification of the changes we make as they happen.

Once you have your local copy of BadgeKit updated with the latest code from GitHub, you can install any outstanding dependencies as follows:

npm install

You may also need to update your databases if the data structures have changed - you will be able to do this using the migration scripts we used when we created the databases above (bin/db-migrate up).

When you are happy that you are up to date with the latest version of BadgeKit and have checked that your app remains functional by running a local instance with the new code, you can commit the changes and push to your remote server as follows (example for Heroku):

git add .
git commit -m "update"
git push heroku master

You can replace heroku with the name of your remote if necessary - use git remote to see the names of any remotes you have been working with; typically this will include the branch you cloned from (most likely origin) and the one your own online BadgeKit instance is hosted at (heroku in the above example).

BadgeKit is still under continual development, so it's worth updating your instance pretty regularly at this stage.

Next Steps

If all went well you should now have an instance of BadgeKit to play around with!

If you're having trouble getting BadgeKit setup, check out the Troubleshooting Guide.

While the BadgeKit app handles badge creation/ publishing and application processing, you can able to use the API to present available badges to your community of earners, to let them apply for badges and to communicate with them when badges are awarded.

Once you have BadgeKit set up, you can build an earner-facing site, or plug your existing site into the API. If you aren't looking to build a bespoke site from scratch yourself, check out these available front-ends you can use:

The following represents a typical badging flow with BadgeKit:

Issuer admins use BadgeKit Web app to create and publish badges.
Issuer site uses BadgeKit API to retrieve the details for published badges and list them for earners.
Issuer site accepts earner applications for badges, forwarding the data to the API.
Pending applications appear in BadgeKit Web app, where assessors can review them.
Issuer site receives notification from BadgeKit API at the issuer webhook URL when an application is reviewed. Issuer site then contacts the earner (hopefully offering them the badge).
Earner accepts badge via issuer site - issuer then uses the API to "issue" the badge, creating a badge instance for the earner email.
Issuer site receives notification from the API of badge being issued via the webhook URL - issuer can then follow up with the earner if necessary.

The above flow relates to badges issued via the assessment process. You can also issue badges using claim codes or direct from within the BadgeKit Web app, using the "Issue by Email" option. Note that whichever issuing approach you use, BadgeKit will not carry out any communication with your earners. Instead the API sends notification that a badge has been awarded - you can receive this notification at your webhook URL and contact the earner as required.

If you have any feedback on your experiences with BadgeKit or suggestions on how we can make it easier to use these tools, we'd love to hear them.

In the meantime, you may find the following additional resources useful:

You will also find FAQs in the Help section of BadgeKit.

Help

For support working with BadgeKit or Open Badges, use any of the following channels:

Post general questions in our Community Google Group and post technical questions in our Dev Google Group.
Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel.
Email questions directly to badges@mozillafoundation.org and a member of the team will follow-up.
Follow or tweet the Open Badges team @OpenBadges.
Get involved or submit issues via the GitHub repos - feedback is always appreciated!

Introduction

Home

Users

BadgeKit Tutorial

Developers

Concepts

Design

History

Provide feedback

Saved searches

Use saved searches to filter your results more quickly