Badgr Hosts

Operate your own Open Badges infrastructure.

While accounts on Badgr.io are free, and Concentric Sky offers hosted auto-scaling Badgr clusters located in specific regions to comply with local privacy regulations, organizations sometimes choose to run their own Badgr server to offer Open Badges functionality within their organization. Hosting your own instance of Badgr allows complete control over the data and deployment, as well as the ability to enable optional restrictions not in place on Concentric Sky’s cloud hosting. Badgr is open source software run in production on servers around the world. To run Badgr yourself, configure and run both of its constituent repositories from one or more web servers on the public internet.

Install for a Local Machine

The install procedure looks similar for a local unix-based machine as it does for a production deploy, except for the final configuration steps.

Project Structure

Your project components that you need to establish include the badgr-server code, badgr-ui code, and python “virtual environment”. We often use a structure like the following to organize them:

badgr
├── badgr-server
├── badgr-ui
└── env-badgr-20180321

To get started, create the outer badgr directory.

Install and configure Badgr Server

Install system-wide prerequisites. Install method varies by system and preference:

  • git
  • python 2.7.x
  • virtualenv
  • mysql
  • cairo (SVG utility)

Start in your badgr directory by cloning source code: git clone https://github.com/concentricsky/badgr-server.git

Change to the badgr-server directory and copy local settings cp apps/mainsite/settings_local.py.example apps/mainsite/settings_local.py.

  • Create and activate a local python 2.7 virtual environment with virtualenv.
  • Create a local MySQL database and configure settings to match your local database, cache (if you prefer something other than the default in-memory-cache), and preferred development environment email backend (if you prefer to use something other than the default console logging).
  • Install required dependencies using pip install -r requirements.txt
  • Let Django configure your database by running migrations as a management command from the badgr-server directory: ./manage.py migrate
  • Create a superuser that can access administrative settings using ./manage.py createsuperuser, following prompts.
  • Run your local development server: ./manage.py runserver
  • Log into http://localhost:8000/staff to configure

Optional Badgr Server Settings

  • OPEN_FOR_SIGNUP = True This defaults to True, but allows you to turn off signup if you would like to use Badgr for only single-account use or to manually create all users in /staff.
  • BADGR_APPROVED_ISSUERS_ONLY = False: This defaults to False, but if you choose to use the BADGR_APPROVED_ISSUERS_ONLY flag, this means new user accounts will not be able to define new issuers (though they can be added as staff on issuers defined by others) unless they have the Django user permission ‘issuer.add_issuer’. The recommended way to grant users this privilege is to create a group that grants it in the /staff admin area and add the appropriate users to that group.

Install and run Badgr UI

Start in your badgr directory and clone badgr-ui source code: git clone https://github.com/concentricsky/badgr-ui.git badgr-ui

  • Change to the badgr-ui directory and install dependencies. We recommend using a recent version of node and npm to run npm install.
  • To run the Angular badgr-ui local server run npm run start

Setting up a Production Envioronment

To deploy to production, there are a number of configuration settings that will differ from your local environment:

  • Choose domain names for badgr-server and badgr-ui, like badges.myorg.org and www.badges.myorg.org respectively.

Badgr Server

  • Install prerequisites on the server(s), which may vary from your development environment. A list of known system-specific requirements is listed in the Badgr-server README.
  • Configure load balancing and autoscaling if desired. Options vary depending on cloud provider.
  • Configure an Email backend. A number of options are available. An easy one to use if you deploy to AWS is Amazon’s Simple Email Service (SES).
  • Configure a production webserver with WSGI. See How to Deploy with WSGI.
  • Configure SSL certificate for your server
  • Deploy and configure cache (shared across all servers in a cluster if more than one)
  • Configure database. Run migrations from one server node
  • Advanced/optional: Configure celery task node(s) for asynchronous processing. There are very few tasks at present and low cost to running them synchronously in web requests at this time.
  • Configure CORS settings for BadgrApp for the Badgr UI domain.

Badgr UI

  • run npm build:prod
  • Deploy the resulting dist folder containing all built assets to a web server