Skip to content
This repository

Mozilla Open Badges Backpack

Merge pull request #987 from jslag/development

Fix link to Issuer API docs
latest commit 20c06c0b96
Chris McAvoy cmcavoy authored
Octocat-spinner-32 .puppet-manifests Also change the name of the npm-package 'up' to up-time in puppet script October 07, 2013
Octocat-spinner-32 acceptance-test added docs for sauce labs. April 19, 2013
Octocat-spinner-32 bin Use messina module September 23, 2013
Octocat-spinner-32 check fix spelling March 19, 2012
Octocat-spinner-32 controllers Make demo badges use utils.fullUrl to handle remote/local port stuff … December 18, 2013
Octocat-spinner-32 docs Merge remote-tracking branch 'upstream/development' into development November 27, 2013
Octocat-spinner-32 fakeissuer Add IE8 support to fakeissuer. November 25, 2013
Octocat-spinner-32 lib Test SVG badges with award. November 26, 2013
Octocat-spinner-32 migrations Add `baked` field for images November 25, 2013
Octocat-spinner-32 models Fix rebake error December 13, 2013
Octocat-spinner-32 scripts Add a basic nagios check against the backer API March 19, 2012
Octocat-spinner-32 static Adds CSS to fix #971: huge badge images in groups December 11, 2013
Octocat-spinner-32 test Convert images back to base64 before reinserting them. December 03, 2013
Octocat-spinner-32 var Initial migration, starting to write the BrowserID stuff. August 19, 2011
Octocat-spinner-32 views Use new favicon December 03, 2013
Octocat-spinner-32 .gitignore Merge pull request #952 from stenington/docs November 25, 2013
Octocat-spinner-32 .gitmodules Twitter bootstrap has moved from github user twitter to twbs August 07, 2013
Octocat-spinner-32 .jshintrc Style consistency; less noisy tests; new default make task. April 30, 2012
Octocat-spinner-32 .travis.yml And set DISABLE_PHANTOM_TESTS for travis September 13, 2013
Octocat-spinner-32 LICENSE Add a LICENSE file stating we're using MPL 2.0 March 30, 2012
Octocat-spinner-32 Makefile Merge branch 'development' into 503-spec-implementation March 08, 2013
Octocat-spinner-32 Procfile adding .idea to .gitignore for jetbrains users September 13, 2013
Octocat-spinner-32 Fix link to Issuer API docs January 03, 2014
Octocat-spinner-32 Vagrantfile oops >_> October 01, 2012
Octocat-spinner-32 app.js Enable statsd for all routes September 17, 2013
Octocat-spinner-32 middleware.js Let whitelisted pages generate CSRF tokens September 30, 2013
Octocat-spinner-32 package.json 1.0.43 December 18, 2013

Mozilla Open Badges

Build Status


We intend to provide an open set of specifications, tools and services for generating verifiable badges that users can take with them wherever they go and use however they like.

The latest open standard we released can be found in the latest assertion specification. The assertion includes the open standard, the metadata specification, we defined.

For more information, check out

I'm an Issuer, how do I use this?


  • Webserver capable of serving requests to the general internet.
  • Ability to make a POST request from your server backend and read a JSON response.
  • Email addresses of the users you wish to issue badges.
  • Badge image must be in PNG format.

Usage example:

  1. Generate an assertion (see below) for the user recieving the badge.
  2. Store that assertion at a public-but-secret URL and serve it with content-type: application/json

    • The assertion contains private information about a user, so you want a non-predictable URL scheme to prevent automated scraping.

    • This URL should be stable - any badge issued from it relies on its existence for verification.

    • Both of these problems will be solved in the near-term future by supporting signed assertions, so you'll only need to expose a URL containing your public key.

  1. Make a POST request to the open badge creator with the assertion URL. If validation passes, you will receive an HTTP 200 with content-type: image/png, the body being a your badge.image with the assertion URL baked into it.
  2. Send/give the image to the user (for example, email it).

The Issuer Javascript API

We have an easy to use API built for Issuers to easily push badges into Users Backpacks, giving the User the ability to approve the push through a lightboxed modal. The API is written in Javascript, and is includable in your project with just a few lines of JS. Full documentation is available here.


Please see the documentation on Assertions to learn how to format your assertions, and [see the documentation on Badge Baking][baking-latest] to learn more about how to use the baking API and what kind of responses to expect in case of error.

I want to play with the code, where do I start?

The easy way*

Use Vagrant. vagrant up in the project root will spin up a fully provisioned VM (it'll take about two or three minutes, longer if you don't have a lucid32 box), vagrant ssh to get into the VM, then start-server will start up the server at http://localhost:8888. The server will also watch for changes, so you don't have to manually reload it.

For Windows users

Install Vagrant and VirtualBox. Vagrant will try to install in C:\vagrant, which is a protected location in Windows. Instead, tell it to install in C:\Program Files (if you're on 32 bit windows) or C:\Program Files (x86) (if you're on 64 bit windows) instead - don't worry, this will actually create a C:\Program Files\vagrant folder.

Ensure that your PATH variable contains the VirtualBox binaries folder: Go to your Control Panel -> System -> Advanced system settings -> "Environment Variables" button -> in the system variable section scroll down to the PATH variable, hit "edit" and add C:\Program Files\VirtualBox. After making sure this is the case, in the openbadges repo, run:

C:\...\Openbadges>"c:\Program Files (x86)\Vagrant\bin\vagrant.bat" up

This will do all the VM building. You may be prompted by the windows firewall and UAC to allow VirtualBox network and disk access: you'll have to allow this, otherwise things won't work. When the VM creation is done, let vagrant discover that it can't actually do SSH on windows:

C:\...\Openbadges>"c:\Program Files (x86)\Vagrant\bin\vagrant.bat" ssh

This will generate an output similar to the following:

`vagrant ssh` isn't available on the Windows platform. You are still able
to SSH into the virtual machine if you get a Windows SSH client (such as
PuTTY). The authentication information is shown below:

Port: 2229
Username: vagrant
Private key: C:/Users/You/.vagrant.d/insecure_private_key

If you don't already have it installed, get PuTTY or another SSH client and log into with the username "vagrant" and password "vagrant", using the SSH key that vagrant generated in the indicated directory (Connection -> SSH -> Auth -> "browse" button). Putty will expect a .ppk file, so just tell it to show all files (.) and select the insecure_private_key file. Connect, and you should get into the Vagrant VM just fine.

Once connected to the VM, you can now start the server using:

vagrant@lucid32:~$ start-server

and then back in windows you can fire up your favourite browser and connect to the OpenBadges server you now have running on localhost:


A Warning

:warning: Some developers have been having trouble with vagrant, and don't use it any more. Vagrant support may be out of date.

The hard way

  1. Setup a MySQL database. Create a database and a user with full privileges on that db. For example:

    CREATE DATABASE openbadges;
    GRANT ALL PRIVILEGES ON openbadges.* TO badgemaker@localhost IDENTIFIED BY 'secret';
    CREATE DATABASE test_openbadges;
    GRANT ALL PRIVILEGES ON test_openbadges.* to badgemaker@localhost IDENTIFIED BY 'secret';
  2. Copy the openbadges/lib/environments/local-dist.js to openbadges/lib/environments/local.js and edit the configuration to match your local development environment. The MySQL database credentials should match step #1. For example:

    database: {
      driver: 'mysql',
      host: '',
      user: 'badgemaker',
      password: 'secret',
      database: 'openbadges'
  3. Install external tools:

    • PhantomJS: We use PhantomJS for running unit tests. On a debian based Linux system you can run sudo apt-get install phantomjs to install and run phantomjs --version to check it is installed. For other systems you can try downloading and installing it or building it from source.
  4. Install local dependencies: npm install

  5. Install submodules: git submodule update --init

  6. Run the test suite: npm test

  7. Start your server: npm start

No matter which way you choose, you should join the Open Badges Google Group. If you have any problems setting up the environment, feel free to post a message to the list.

Optional: A real hostname

I like to be able to use http://openbadges.local for accessing the project. Assuming you used vagrant, you can change the hostname in local.js and do sudo echo " openbadges.local" >> /etc/hosts to make it happen. If you're on OS X, you can also use Gas Mask for temporary hosts file switching rather than having to manually edit /etc/hosts

Database Migrations

If you need to modify the database schema, you'll want to create a migration. You can do this as follows:

  1. Come up with an alphanumeric name for your migration, e.g. add-issuer-column.

  2. Run ./bin/db-migrate create add-issuer-column. This will create a new JS file preixed with a timestamp in the migrations directory. Something like the following should be displayed:

    [INFO] Created migration at

  3. Edit the new JS file as per the node-db-migrate instructions.

  4. Try out your migration using ./bin/db-migrate up.

  5. Try rolling back your migration using ./bin/db-migrate down.

And finally, note that during development, npm start automatically runs ./bin/db-migrate up for you. For production use, you'll need to manually run this command yourself whenever you deploy changes that involve a schema change.

If you want to write tests for your migration, check out test/migration.test.js for inspiration.


The codebase behaves slightly differently when run in an environment where environment variable NODE_ENV=production. These differences include:

  • less verbose logging
  • using precompiled templates for client-side rendering
    • run bin/template-precompile to generate
  • "Test Site" banner will not show in the UI

Related Projects

Something went wrong with that request. Please try again.