Commit | Line | Data |
---|---|---|
e35dd66e DT |
1 | LibrePlanet 2015 |
2 | ================ | |
3 | ||
17eaac29 ZR |
4 | This is the static HTML site for LibrePlanet 2015. Read on for |
5 | instructions on how to setup your development environment. | |
6 | ||
4511d614 DT |
7 | The repository has a master (development) branch and a stable |
8 | (live) branch. To work on it, you'll edit your checkout of the | |
9 | master branch until you are satisfied, push it to the master | |
10 | branch on the Web server (<http://wiki-dev0.libreplanet.org>), | |
11 | make sure it works well and make sure it works well. Then | |
12 | you'll copy it over to your checkout of the stable branch, | |
13 | then push that to the stable branch on the Web server | |
d4688c12 ZR |
14 | (<http://libreplanet.org>). |
15 | ||
e35dd66e DT |
16 | Setting Up Apache |
17 | ----------------- | |
18 | ||
e513b11d | 19 | Apache is required in order to replicate the appearance of the website |
4511d614 DT |
20 | on the live and staging servers on your machine. If you don't want to |
21 | install Apache, you can still work on the site, you just won't be able | |
22 | to see what it looks like until you push to the remote. | |
23 | ||
24 | Modifying Apache's configuration files and running its executables | |
25 | typically requires root access. So, you will most likely need to run | |
26 | the commands below as the root user using `sudo`. | |
e513b11d DT |
27 | |
28 | ### Enable server-side include module | |
29 | ||
30 | ``` | |
31 | a2enmod include | |
32 | ``` | |
33 | ||
7389a047 ZR |
34 | If this doesn't work, you may not have Apache installed. Install the |
35 | package apache2 from your package manager. | |
36 | ||
e513b11d DT |
37 | ### Create virtual host |
38 | ||
7389a047 | 39 | Create a new file called libreplanet in `/etc/apache2/sites-available` with the following contents: |
e513b11d DT |
40 | |
41 | ``` | |
42 | <VirtualHost *:80> | |
43 | ServerName lp2015.libreplanet.org | |
44 | DocumentRoot /path/to/libreplanet-static | |
45 | ||
46 | <Directory /> | |
47 | Options FollowSymLinks | |
48 | AllowOverride All | |
49 | </Directory> | |
50 | <Directory /path/to/libreplanet-static> | |
51 | Options Indexes FollowSymLinks MultiViews | |
52 | Options +Includes | |
53 | XBitHack on | |
54 | AllowOverride All | |
55 | Order allow,deny | |
56 | allow from all | |
57 | </Directory> | |
58 | ||
59 | ErrorLog ${APACHE_LOG_DIR}/error.log | |
60 | LogLevel warn | |
61 | CustomLog ${APACHE_LOG_DIR}/access.log combined | |
62 | </VirtualHost> | |
63 | ``` | |
64 | ||
7389a047 | 65 | Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local |
e513b11d DT |
66 | git repository. |
67 | ||
68 | ### Enable virtual host | |
69 | ||
70 | ``` | |
71 | a2ensite your-virtual-host | |
72 | ``` | |
73 | ||
7389a047 | 74 | Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet). |
e35dd66e | 75 | |
e513b11d | 76 | ### Restart Apache |
e35dd66e | 77 | |
e513b11d DT |
78 | ``` |
79 | service apache2 restart | |
80 | ``` | |
81 | ||
82 | ### Edit your hosts file | |
83 | ||
84 | Edit your system's `/etc/hosts` file and add the following to the bottom: | |
85 | ||
86 | ``` | |
87 | 127.0.0.1 lp2015.libreplanet.org | |
88 | ``` | |
89 | ||
90 | ### Test | |
91 | ||
92 | Visit <http://lp2015.libreplanet.org/2015> in your web browser. If | |
93 | everything is configured properly, you will see the LibrePlanet 2015 | |
94 | site, complete with header, sidebar, and footer. | |
95 | ||
742fb594 DT |
96 | Creating a New Page |
97 | ------------------- | |
98 | ||
99 | ### Boilerplate | |
100 | ||
7389a047 | 101 | Add the following to your new page (it should remain commented out, as that is the syntax for SSI): |
742fb594 DT |
102 | |
103 | ``` | |
fd523856 | 104 | <!--#include virtual="/server/2015/header.html"--> |
38fb2855 | 105 | <!--#include virtual="/server/2015/banner.html"--> |
106 | <!--#include virtual="/server/2015/sidebar.html"--> | |
fd523856 | 107 | <!--#include virtual="/server/2015/footer.html"--> |
108 | <!--#include virtual="/server/2015/close.html"--> | |
742fb594 DT |
109 | ``` |
110 | ||
38fb2855 | 111 | This will include the header, banner, sidebar, footer and closing tags |
112 | saving you from duplicating HTML. | |
fd523856 | 113 | |
114 | If JS is needed for a page, then create a file, containing the JS | |
115 | includes, in `/server/2015/` & use SSI to include it in the page. | |
742fb594 | 116 | |
38fb2855 | 117 | Use `/server/2015/boilerplate.html` to start a new page. |
118 | ||
742fb594 DT |
119 | ### Add Your Markup |
120 | ||
38fb2855 | 121 | Add HTML markup in-between the sidebar and footer includes. |
742fb594 DT |
122 | |
123 | ### Enable SSI | |
e35dd66e DT |
124 | |
125 | Files that contain include directives must be marked as executable | |
126 | otherwise Apache will not parse them. The directive `XBitHack on` | |
127 | enables this behavior. | |
e513b11d DT |
128 | |
129 | To mark a file as executable, run: | |
130 | ||
131 | ``` | |
132 | chmod +x foo.html | |
133 | ``` | |
134 | ||
135 | Replace `foo.html` with the desired file name. | |
136 | ||
137 | Deploying to Staging/Live Servers | |
138 | --------------------------------- | |
139 | ||
140 | A system of git hooks automates deployment to the staging and live | |
141 | servers. When you push to the `master` branch, the site is deployed | |
0a048e93 | 142 | to <http://wiki-dev0.libreplanet.org/2015>. When you push to the |
510de517 | 143 | `stable` branch, the site is deployed to <http://libreplanet.org>. |
a4d89204 | 144 | |
b60c5e5f DT |
145 | When you're happy with the state of the master branch and want to |
146 | deploy live, do the following: | |
147 | ||
148 | ``` | |
149 | git checkout stable | |
150 | git merge master | |
151 | git push | |
152 | ``` | |
153 | ||
154 | This merges the master branch with the stable branch, updates the | |
155 | remote repository on the git server, and triggers a deploy to | |
156 | <http://libreplanet.org>. | |
157 | ||
a4d89204 DT |
158 | CSS and JavaScript |
159 | ------------------ | |
160 | ||
161 | This site is built with: | |
162 | ||
163 | * [Bootstrap 3.2.0](https://github.com/twbs/bootstrap/releases/download/v3.2.0/bootstrap-3.2.0-dist.zip) | |
164 | * [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.1.js) |