readme.md 4.85 KB
Newer Older
1
# Better Builder
Aral Balkan's avatar
Aral Balkan committed
2

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

5
6
7
8
9
10
## Prerequisites

Requires [Node.js](https://nodejs.org) and [npm](https://docs.npmjs.com/getting-started/installing-node).

<small>(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](https://github.com/tj/n) and configure the version that it needs.)</small>

11
12
Supported on Node.js version: 6.11.3 (LTS)

13
14
15
## Installation

Normally, you will not need to install this project manually, as the [Better iOS app](https://source.ind.ie/better/app) will install it for you. In case you want to install it separately from the iOS app, just run:
16

17
	./install
18

19
20
## Usage

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

23
	./dev
24

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

27
To see the generated app data, run the [Better iOS app](https://source.ind.ie/better/app) in the iOS Simulator.
28

29
### Updating generated data locally
30

31
  1. Make a change to a Blockdown format file in your local working copy of the content repository (*~/better.fyi/builder/content/*)
32
  2. `git commit -am "Your change"`
33
  3. `git push origin master`
34

35
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.
36

37
Visit `http://localhost:3000` to see the updated site and *~/better.fyi/builder/site-local/site/blockerList.json* for the updated WebKit blocker list.
38

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
## Pushing to live

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

```bash
git push live master
```

## Deployment

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 *builder.better.fyi*.

The results will be available on next load for the iOS apps and immediately [on the Better web site](https://better.fyi).

You can also see the results of the build on [data.better.fyi](https://data.better.fyi) in the [app](https://data.better.fyi/generated/app/tree/master) and [site](https://data.better.fyi/generated/site/tree/master) generated data repositories.

60
## Production
61

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

64
65
66
1. [Data Server](#data-server)
2. [Web Server](#web-server)
3. [Builder Server](#builder-server)
67
68
69

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

70
71
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.

72
**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 source.ind.ie.)
73

74
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.
75

76
### Common steps
77

78
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):
79

80
81
82
1. Commission an Ubuntu 14.04 LTS server from an OpenStack provider (tested with CloudScale.ch)
2. `ssh ubuntu@builder.yourdoma.in`
3. `sudo apt-get update && sudo apt-get install git`
83

84
### 1. Install the Data Server
85

86
To set up your own version of *data.better.fyi*:
87

88
89
90
91
0. Folow the instructions under [common steps](#common-steps), above.
1. `git clone git@source.ind.ie:better/data-server-setup.git`
2. `cd data-server-setup`
3. `./install`
92

93
### 2. Install the Web Server
94

95
To set up your own version of *(www.)better.fyi*:
96

97
98
99
100
0. Folow the instructions under [common steps](#common-steps), above.
1. `git clone git@source.ind.ie:better/web-server-setup.git`
2. `cd web-server-setup`
3. `./install`
101

102
103
104
105
106
107
108
109
### 3. Install the Builder Server

To set up your own version of *builder.better.fyi*:

0. Folow the instructions under [common steps](#common-steps), above.
1. `git clone git@source.ind.ie:better/builder-server-setup.git`
2. `cd builder-server-setup`
3. `./install`