Troubleshooting BadgeKit

If you're having trouble getting your BadgeKit instance up and running, check below for a solution to your problem. If you haven't done so already, check out the Self-Hosting Guide to ensure you've carried out the necessary setup steps.

If you can't find a solution to your problem here, contact the Open Badges team in the #badges channel on IRC, email us at [email protected] or create a GitHub issue and we'll look into it!

Make sure your BadgeKit API is running.

If you're having trouble running the BadgeKit app or parts of it are failing, particularly published/ archived badges, make sure your BadgeKit API instance is running, as it's required for the app itself to function.

Make sure you have a system in your BadgeKit API database.

When you set the BadgeKit API up, you need to add at least one system to the database. You can use the following for MySQL:

INSERT INTO systems (slug, name) VALUES ('badgekit', 'Your System');

If you're seeing ResourceNotFound, errors this may be the cause.

Check your ports and URLs.

BadgeKit won't run reliably if the URL and port configs aren't set correctly. Check that your BadgeKit OPENBADGER_URL matches the full URL you have the BadgeKit API running on (e.g. http://badgekit.mydomain.com) - by default it will expect port 8080. Your BadgeKit PORT and PERSONA_AUDIENCE values must also match the location you are running the BadgeKit app at. The DATABASE_* values in the BadgeKit config are for the BadgeKit database, NOT the BadgeKit API database, which is defined in its own configuration.

Check your secrets.

Running BadgeKit typically involves two secret values, one for BadgeKit to authenticate communication with the BadgeKit API and one for it to authenticate with the app user. Ensure that the value you specify as MASTER_SECRET in your BadgeKit API instance matches what you have for OPENBADGER_SECRET in your BadgeKit instance.

Additionally, if you plan on using the User API to manage BadgeKit user accounts, you will need the value you specify as API_SECRET for your BadgeKit Web app instance.

Source your configs.

If you're specifying your configurations for BadgeKit as environment variables in a file, make sure you source the file before you attempt to run the app. You can do this as follows:

source env_file

(Replacing env_file with the name of your file.)

At the moment BadgeKit config is only pulled from config.json or the environment, but we're working on supporting config via a standard shell environment file.

Install dependencies.

After cloning the BadgeKit repos (or updating them from GitHub), make sure you install dependencies before you attempt to run. You can do this using the Node Package Manager by running the following in the repo directory:

npm install

If you see any errors installing dependencies, you will need to resolve them before you can get BadgeKit running.

Check your access list syntax.

If you're having trouble logging in with Persona, you may need to alter the syntax you use in the BadgeKit ACCESS_LIST config. For example, in some environments you need to escape certain characters, as in:

"ACCESS_LIST": [\"\^[email protected]\$\"]

This will depend on where you are running the app.