readme.md 4.81 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
13
## 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:
14

15
	./install
16

17
18
## Usage

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

21
	./dev
22

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

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

27
### Updating generated data locally
28

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

33
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.
34

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

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
## 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.

58
## Production
59

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

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

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

68
69
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.

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

72
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.
73

74
### Common steps
75

76
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):
77

78
79
80
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`
81

82
### 1. Install the Data Server
83

84
To set up your own version of *data.better.fyi*:
85

86
87
88
89
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`
90

91
### 2. Install the Web Server
92

93
To set up your own version of *(www.)better.fyi*:
94

95
96
97
98
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`
99

100
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`