Public | Automated Build

Last pushed: 2 years ago
Short Description
a oauth service modified for the Collaborative Technology Alliance (work in progress)
Full Description


A D-CENT project: an easily deployable oauth server for small organisations.

Development VM

You can develop and run the application in a VM to ensure that the correct versions of Stonecutter's dependencies
are installed. You will need VirtualBox, Vagrant and Ansible installed.

First, clone the repository.

Navigate to the ops/ directory of the project and run:

vagrant up development

The first time this is run, it will provision and configure a new VM.

When the VM has started, access the virtual machine by running:

vagrant ssh

The source folder will be located at /var/stonecutter.

After initial setup, navigate to the source directory with:

cd /var/stonecutter


To start the app, run:


To start a web server for the application in development mode, run:

lein ring server-headless

NB: running the application like this will save users into an in memory cache that will be destroyed as soon as the app is shutdown.

Running test suite

To run all tests, use this command:

lein test

Commands and aliases can be found in the project.clj file.

Running the prototype

Simply type:

gulp server

Adding an email provider

Stonecutter can integrate against 3rd party email providers via a shell script interface, which may optionally require
configuration via environment variables.

Scripts for individual mail service providers should be located in the ops/roles/mail/files/providers directory.
These will be copied into a deployment environment by Ansible. Currently, an implementation has been provided for
Mailgun, which can be used as a template.

In order to select which email service is used, set the EMAIL_SERVICE_PROVIDER environment variable. This should
match one of the provider scripts under in the ops/roles/mail/files/providers directory. For example, to use
the Mailgun provider:


For the mailgun example, the following environment variables are also required:

  • EMAIL_DOMAIN_NAME --- the domain name that has been linked to mailgun
  • MAILGUN_API_KEY --- the mailgun api username + key (i.e. a string in the form: "api:api-key"), provided by Mailgun.


The Continuous Delivery build and deployment architecture is documented [here] (

The Hosting Architecture is documented [here] (


Deploying the application using docker

You can deploy the application using Docker. To do so, you will need three containers:
Mongo, Nginx and Stonecutter.

Starting a mongo container

To start a mongo container, run

docker run -d --name mongo mongo

Starting an Nginx container

To start an Nginx container you need

  • an SSL certificate and key
  • a dhparam.pem file
  • an nginx.conf file

You can acquire an SSL certificate and key online inexpensively. You should receive a pair of files, for instance stonecutter.crt and stonecutter.key. Store them in their own directory somewhere safe.

You can generate a dhparam.pem file by running:

openssl dhparam -rand – 2048 > dhparam.pem

You can create an nginx.conf file by copying the following into a new file and replacing the <> appropriately:

events {
http {
  server {
    listen 80;
    return 301 $request_uri;
  server {
    listen 443 ssl;
    ssl_certificate /etc/nginx/ssl/<file name for SSL certificate>;
    ssl_certificate_key /etc/nginx/ssl/<file name for SSL key>;

    ssl_session_cache shared:SSL:32m;
    ssl_session_timeout 10m;

    ssl_dhparam /etc/nginx/cert/dhparam.pem;
    ssl_protocols TLSv1.2 TLSv1.1 TLSv1;

    location / {
      proxy_pass http://<docker ip>:5000;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;

Finally, run the following command:

docker run -v <absolute path to SSL certificates and keys directory>:/etc/nginx/ssl -v <absolute path to conf file>/nginx.conf:/etc/nginx/nginx.conf -v <absolute path to dhparam file>/dhparam.pem:/etc/nginx/cert/dhparam.pem -p 443:443 -d --name nginx-container nginx

Starting a Stonecutter container

To run Stonecutter you need

  • a clients.yml file
  • an rsa-keypair.json
  • a stonecutter.env file

To make a clients.yml file, copy the default one in this project, under Stonecutter/config. It shows the format used by the application.

To get an rsa keypair, see below.

Store both of these two files in their own directory.

To get a stonecutter.env, copy the template that is found in the config folder.

Finally, run this command, replacing <config file path> with the absolute path for the directory storing your config files, and <env file path> with the path to wherever your environment variable file is stored.

docker run -v <config file path>:/var/config --env-file=<env file path> -v <favicon and logo absolute path directory>:/data/stonecutter/static -v <email service directory absolute path>:/var/stonecutter/email_service -p 5000:5000 --link mongo:mongo -d --name stonecutter dcent/stonecutter

An example script for deploying,, is included in the ops directory.

Adding public-private keypair for OpenID Connect

To generate a public-private keypair in Json Web-key (JWK) format, enter the following at the command line:

> lein gen-keypair <key-id>

where the key-id is a custom identifier for the key (for example "20150824-stonecutter").

This will generate output similar to the following:

JWK public key for client:

JWK including private key for stonecutter:

The first JSON document needs to be provided to any clients wishing to use OpenID Connect when interacting with Stonecutter, while the second should be stored in a file --- for example "rsa-keypair.json" --- which should be kept secure.

To deploy Stonecutter with this key, the rsa-keypair.json file needs to be placed in a directory accessible by the deployed instance, and the Stonecutter instance should be started with the environment variable RSA_KEYPAIR_FILE_PATH pointing to its location.

If deploying using the Snap CI tool (, this process is automated by including the rsa-keypair.json file in the secure files for the snap stage responsible for deployment, with the filename "rsa-keypair_<SNAP_STAGE_NAME>.json". The ops/ script will then manage copying the file to the appropriate location on the target, and starting the app with the environment variable set.

Docker Pull Command