Skip to content


Repository files navigation

Annotation Studio

An annotation platform designed for teaching and learning in the humanities, and with aspirations to more general use.

Works with: MIT Annotation Data Store

There are two servers required to run this application. This one, and the MIT Annotation Data Store.

You MUST get the Annotation server running to be able to create or view annotations.

Getting Started

Things to install

Annotation Studio uses PostgreSQL and Ruby

The MIT Annotation Data Store requires Node.js, NPM and MongoDB

General Installation

Use rbenv or rvm to install and run the Ruby version specified in .ruby-version.

(optional additional software: thoughtbot's Laptop repo)

git clone
cd Annotation-Studio

which will:

  • Drop existing databases
  • Run migrations and prepare the test database
  • Seed the application
  • Install the MIT Annotation Data Store under ./tmp/annotation_data_store
  • Create an example application.yml

After setting up the app, run:

bundle exec foreman start -f

to spin up development dependencies. You can exist the development daemons by hitting ctrl-c, per normal unix semantics.

Installation on Heroku

If you would like to run the application on Heroku (recommended), do the following

  • Create a Heroku app heroku apps:create $APPNAME
  • Add the Heroku PostgreSQL add-on heroku addons:add heroku-postgresql
  • Use Figaro to load your application.yml into environment variables and communicate them to Heroku
    • rake figaro:heroku[$APPNAME]


This app uses the apartment gem to allow multiple domains to be hosted in a single instance.

To create a new tenant:

  1. Log in via an AdminUser account to
  2. Add a Tenant record, with the full hostname at which you want users to access the application, and the name of the database to be used to store the tenant's data
  3. Configure DNS for that domain (or subdomain), pointing it to the URL of the application
  4. Add the domain in question to the web server configuration for the application


  1. If a domain does not have a matching Tenant, the default "public" tenant will be used.
  2. Admin users are shared across all tenants, and therefore shouldn't be created and granted to single-tenant users

User Support and Developer forum


Thanks to: