DEPLOYMENT.md

NOTE: this document is outdated and should be updated, it's left here because there is some still some potentially useful information.
Reader beware.

How to deploy BrowserID

This describes how to take the code here, put it on a server, and build a service like persona.org.

So what are we deploying, anyway?

• the browserid server - a node.js server which implements a web services api, stores a record of users, the email addresses they've verified, a bcrypted password, outstanding verification tokens, etc.
• the verifier - a stateless node.js server which does cryptographic verification of assertions. This thing is hosted on persona.org as a convenience, but people using browserid can choose to relocated it if they want to their own servers.
• the persona.org website - the templates, css, and javascript that make up the visible part of persona.org
• the javascript/HTML dialog & include library - this is include.js and the code that it includes, the bit that someone using browserid will include.

Overview

Software in use

This document assumes we're deploying on an Ubuntu 10.04.1 LTS box, and using the following software:

• nginx - frontend web server that handles static content and serves as a reverse proxy for node.js servers running on localhost

  config: /etc/nginx/conf/nginx.conf

• node.js - all non-static servers run with node. modules are installed using npm in /home/http/node_modules

• monit - provides monitoring and automatic restarting of node.js servers when they go down (by accident or upon code publishing).

  config files are: /etc/monitrc, and /etc/monit.d/*

  helper script that starts node servers: /etc/monit.d/start_node_server

• gitolite - installed under the git user to provide multi-user ssh based git access. post-update hook handles updating code and restarting servers.

  hook: /home/git/.gitolite/hooks/common/post-update

Permissions conventions

• nginx runs as user 'www-data'
• node.js servers run as user 'www-data'
• when git pushing, all publishing and restarting runs as user 'git'

Setup

1. Install gitolite

This step is optional. gitlite turns a normal unix machine into a "git server". All that gitolite does is provide some utilities and the infrastructure required to make it possible for multiple users to authenticate to a particular user on the box using ssh keys for the purposes of updating code. While requiring a bit of setup, in practice this is a fabulously lightweight way to make the releases process sing.

Let's get started:

1. create a "git" user: sudo adduser git
2. install git if required: sudo apt-get install git-core
3. become user git: sudo su -s /bin/bash git
4. hop into your home directory: cd
5. install gitolite: This.
6. add a browserid repo: This.

At this point you've morphed your servers into git servers. Go ahead and add a remote to your local copy of the browserid repo and push to it: git remote add shortaliasforthenewvm git@myserver:browserid.git && git push --all shortaliasforthenewvm

Now you have a clone of your browserid repository that's trivial to update. You can use ssh keys with passphrases and ssh-agent if security is a concern.

2. Install node.js

At present we're running node.js 0.4.10. Lastest along the 4 line should work: