readme.md 3.34 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
## Development
6

7
	./install
8

9
10
11
## Usage

To generate the data, run:
12

13
	./dev
14

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

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

19
To update the generated data (locally):
20

21
  1. Make a change to a Blockdown format file in your local working copy of the content repository (*~/better.fyi/builder/content/*)
22
23
24
  2. `git commit -am "Your change"`
  3. `git push`

25
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.
26

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

## Production
30

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

33
34
35
1. [Data Server](#data-server)
2. [Web Server](#web-server)
3. [Builder Server](#builder-server)
36
37
38

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

39
40
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.

41
**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.)
42

43
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.
44

45
### Common steps
46

47
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):
48

49
50
51
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`
52

53
### 1. Install the Data Server
54

55
To set up your own version of *data.better.fyi*:
56

57
58
59
60
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`
61

62
### 2. Install the Web Server
63

64
To set up your own version of *(www.)better.fyi*:
65

66
67
68
69
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`
70

71
72
73
74
75
76
77
78
79
80
### 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`