Generates data for Better site and iOS app from Blockdown-formatted authored content.

Better Builder

Builds the data for the Better site and app using authored Better content in Blockdown format.


Requires Node.js and npm.

(npm is automatically installed with recent versions of Node. The actual version of Node you have is unimportant as the installation script will install n and configure the version that it needs.)


Normally, you will not need to install this project manually, as the Better iOS app will install it for you. In case you want to install it separately from the iOS app, just run:



To start the fully-offline local development environment and run your first build of the Better content, run:


To see the generated site, visit http://localhost:3000

To see the generated app data, run the Better iOS app in the iOS Simulator.

Updating generated data locally

  1. Make a change to a Blockdown format file in your local working copy of the content repository (~/
  2. git commit -am "Your change"
  3. git push origin master

At this point, your commit will simulate the Gitlab web hook that the production environment uses and trigger the Better build process. That, in turn, will push to the local site.

Visit http://localhost:3000 to see the updated site and ~/ for the updated WebKit blocker list.

Pushing to live

If you have commit rights to the content or theme repositories, you can push to live with:

git push live master


Deploying content updates to the production environment is done via Git tags. If you have commit rights for the content repository, you can deploy to the production environment with:

  1. git tag -s "YYYYMMDD-000N"
  2. git push live --tags

This will trigger a build on

The results will be available on next load for the iOS apps and immediately on the Better web site.

You can also see the results of the build on in the app and site generated data repositories.


To run Better in production, you will need to set up three servers:

  1. Data Server
  2. Web Server
  3. Builder Server

Each of the production servers has an automated installation script where you can also customise the installation based on your own domain, etc.

Please note that the order of installation is important. The Web Server requires a reference to the Data Server during installation and the Builder server requires references to both the Data Server and the Web Server. So install the Data Server first, then the Web Server, and, finally, the Builder Server, in that order.

Important: you do not need to set up a live production environment in order to test Better, develop on it, and develop new content for it. To carry out those tasks, simply install the builder locally using the ./install script to set up a fully offline local environment that simulates the production environment described below. (You will need Internet access only during the installation process so that the installation script can clone the initial repositories from

You only need to set up a production environment if you want to provide your own hosted version of Better. While this is possible, we encourage you to contribute to the main project whenever possible.

### Common steps

Repeat the following steps for all three installations (to get a plain vanilla OpenStack Ubuntu installation to the state where you can clone the installation script):

  1. Commission an Ubuntu 14.04 LTS server from an OpenStack provider (tested with
  2. ssh
  3. sudo apt-get update && sudo apt-get install git

1. Install the Data Server

To set up your own version of

  1. Folow the instructions under common steps, above.
  2. git clone
  3. cd data-server-setup
  4. ./install

### 2. Install the Web Server

To set up your own version of (www.)

  1. Folow the instructions under common steps, above.
  2. git clone
  3. cd web-server-setup
  4. ./install

3. Install the Builder Server

To set up your own version of

  1. Folow the instructions under common steps, above.
  2. git clone
  3. cd builder-server-setup
  4. ./install