An annotation platform designed for teaching and learning in the humanities, and with aspirations to more general use.
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.
Annotation Studio uses PostgreSQL
The MIT Annotation Data Store requires Node.js (0.10.21), NPM (1.3.11) and MongoDB
Set up Rails (if you haven't yet, try: [thoughtbot's Laptop repo] (https://github.com/thoughtbot/laptop))
annotation-studio```
cd annotation-studio./bin/setup
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 Procfile.devto spin up development dependencies. You can exist the development daemons by hitting ctrl-c, per normal unix semantics.
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- Don't worry about providing db configuration, [Heroku will do it for you] (https://devcenter.heroku.com/articles/heroku-postgresql#connecting-in-rails)
- Use Figaro to load your
application.ymlinto environment variables and communicate them to Herokurake 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:
- Tenant banner image
- Tenant accent color (hex code)
- Upload banner image to
app/assets/images/- A lot of tenants provide large banner images (3MB+) - in these cases, it's a good idea to resize the image by 50% or so.
- Create tenant metadata file in
app/views/saml/(use an existing tenant metadata file as a guide) - Create tenant brand file in
app/views/shared/(use an existing tenant brand file as a guide) - Add entry for new tenant to
config/domain_specific/config.yml(use an existing tenant entry as a guide) - Precompile assets:
RAILS_ENV=production bundle exec rake assets:precompile && git add public/assets/ && git commit -m "Add precompiled assets"
- Create property for new tenant at Admin > Create Property, then create data stream for newly created tenant property
- Data stream platform: Web
- Note the created Measurement ID (“G-XXXXXXXX”) — this will be used when creating a tenant record in the admin dashboard
- Add new tenant record to Tenants menu in admin dashboard at Annotation Studio Dashboard - Tenants (use existing tenant record as a guide)
- If setting up a staging site, admin dashboard is at Annotation Studio Dashboard - Tenants (Staging)
- @jamiefolsom typically creates a CNAME record for the new tenant; once this is done, add the new domain to the
cove-studioapp in Heroku under Settings > Domains
- Run the
copy_vetted_documentsrake task through the Heroku CLI:heroku run rake copy_vetted_documents[source-db,destination-db] -a cove-studio
source-dbvalue is usuallycove-studio
- Using rails console, create a new User for Dino Felluga ([email protected])
- Be sure to switch over to new tenant database first (
Apartment::Tenant.switch!(‘name-of-tenant-db) - Add admin role to user (
User.find(1).set_roles = [“admin”])
- In the Rails console, check the list of roles with
Role.all - There should be
student,teacher, andadmin - Create any that don't already exist
You will need to integrate COVE with the new tenant's SAML system. There are certain requirements for the settings:
- encryptAssertions should be set to false
- X509 fingerprint (usually the client provides a full certificate - you can Google for a website that converts it to a fingerprint)
- Attributes that need to be released by the client:
- email: 'urn:oid:0.9.2342.19200300.100.1.3'
- firstname: 'urn:oid:2.5.4.42'
- lastname: 'urn:oid:2.5.4.4'
There will still be issues, because every school's system is just a little bit different.
A common issue is that the school forgets to disable encryptAssertions - when there are login issues, always double-check for this first. A typical sign of encryptAssertions being set incorrectly is when the user seems to sign in successfully, but is kicked back to the homepage. If you watch the server logs, you'll see Authentication failure! invalid_ticket: OneLogin::RubySaml::ValidationError, An EncryptedAssertion found and no SP private key found on the settings to decrypt it., confirming that the setting is incorrect on the tenant's end.
If the school uses Microsoft Azure, releasing the correct attributes in a way that COVE understands is a bit counterintuitive. For each attribute, the name field should be the "urn:oid" identifier from above.
The setup that Azure requires is:
| Name | Source Attribute |
|---|---|
| urn:oid:2.5.4.42 | user.givenname |
| urn:oid:2.5.4.4 | user.surname |
| urn:oid:0.9.2342.19200300.100.1.3 | user.mail |
The "namespace" field on the names should be kept empty (there may be something there by default).
As of this writing, two COVE tenants use OpenAthens.
OpenAthens requires a slightly different metadata file. In each of the two cases, the tenant had to do some special setup on their side.
Take a look at doc/openathens_example_metadata.xml for an example - this tenant reached out to OpenAthens support after lots of back-and-forth with us, and they provided the tenant with this working metadata file.
Especially note the wantsAssertionsSigned="false". Turning off encrypted assertions tends to be a pain point for new tenants, and OpenAthens makes it especially challenging.
- If a domain does not have a matching Tenant, the default "public" tenant will be used.
- Admin users are shared across all tenants, and therefore shouldn't be created and granted to single-tenant users
For future reference, the Mongo query for updating annotations when a tenant changes their name/email is available at doc/torontomu_annotations_mongo_query.
http://support.annotationstudio.org
Thanks to:
- NEH Office of Digital Humanities who has funded this project
- OKFN for supporting [The Annotator] (http://annotatorjs.org)
- Nick Stenning for being awesome and for leading the Annotator developer team
- Dan Whaley, Randall Leeds and hypothes.is for being awesome and supporting the Annotator Community
- The Annotator community for plugins and being awesome.
- MIT HyperStudio
- http://hyperstudio.mit.edu/
- Jamie Folsom @jamiefolsom
- Liam Andrew @mailbackwards
- Andrew Magliozzi @andrewmagliozzi
- Daniel Collis-Puro @djcp
- Seth Woodworth @sethwoodworth
- Ayse Gursoy @gursoy
- Jacob Hilker @jhilker