/2017/README.md: Remove Schedule Markup section.
[libreplanet-static.git] / 2017 / README.md
1 LibrePlanet 2017
2 ================
3
4 This is the static HTML site for LibrePlanet 2017. Read on for
5 instructions on how to setup your development environment.
6
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
14 (<http://libreplanet.org>).
15
16 Setting Up Apache
17 -----------------
18
19 Apache is required in order to replicate the appearance of the website
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`.
27
28 ### Enable server-side include module
29
30 ```
31 a2enmod include
32 ```
33
34 If this doesn't work, you may not have Apache installed. Install the
35 package apache2 from your package manager.
36
37 ### Create virtual host
38
39 Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
40
41 ```
42 <VirtualHost *:80>
43 RewriteEngine on
44 ServerName local-dev.libreplanet.org
45 ServerAdmin webmaster@localhost
46 DocumentRoot /local-path/path-to-site
47 <Directory /local-path/path-to-site/>
48 Options Indexes FollowSymLinks MultiViews
49 AllowOverride All
50 Require all granted
51 Order deny,allow
52 deny from none
53 allow from all
54 SSILegacyExprParser on
55 Options +Includes
56 XBitHack on
57 </Directory>
58 ErrorLog /home/owner/libreplanet-static/logs/error.log
59 CustomLog /home/owner/libreplanet-static/access.log combined
60 </VirtualHost>
61 ```
62
63 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
64 git repository.
65
66 ### Enable virtual host
67
68 ```
69 a2ensite your-virtual-host
70 ```
71
72 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
73
74 ### Restart Apache
75
76 ```
77 service apache2 restart
78 ```
79
80 ### Edit your hosts file
81
82 Edit your system's `/etc/hosts` file and add the following to the bottom:
83
84 ```
85 127.0.0.1 lp2017.libreplanet.org
86 ```
87
88 ### Test
89
90 Visit <http://lp2017.libreplanet.org/2017> in your web browser. If
91 everything is configured properly, you will see the LibrePlanet 2017
92 site, complete with header, sidebar, and footer.
93
94 Creating a New Page
95 -------------------
96
97 ### Boilerplate
98
99 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
100
101 ```
102 <!--#include virtual="/2017/includes/header.html"-->
103 <!--#include virtual="/2017/includes/banner.html"-->
104 <!--#include virtual="/2017/includes/sidebar.html"-->
105 <!--#include virtual="/2017/includes/footer.html"-->
106 <!--#include virtual="/2017/includes/close.html"-->
107 ```
108
109 This will include the header, banner, sidebar, footer and closing tags
110 saving you from duplicating HTML.
111
112 If JS is needed for a page, then create a file, containing the JS
113 includes, in `/2017/includes/` & use SSI to include it in the page.
114
115 Use `/2017/includes/boilerplate.html` to start a new page.
116
117 ### Add Your Markup
118
119 Add HTML markup in-between the sidebar and footer includes.
120
121 ### Enable SSI
122
123 Files that contain include directives must be marked as executable
124 otherwise Apache will not parse them. (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
125
126 To mark a file as executable, run:
127
128 ```
129 chmod +x foo.html
130 ```
131
132 Replace `foo.html` with the desired file name.
133
134 Deploying to Staging/Live Servers
135 ---------------------------------
136
137 A system of git hooks automates deployment to the staging and live
138 servers. When you push to the `master` branch, the site is deployed
139 to <http://wiki-dev0.libreplanet.org/2017>. When you push to the
140 `stable` branch, the site is deployed to <http://libreplanet.org>.
141
142 When you're happy with the state of the master branch and want to
143 deploy live, do the following:
144
145 ```
146 git checkout stable
147 git merge master
148 git push
149 ```
150
151 This merges the master branch with the stable branch, updates the
152 remote repository on the git server, and triggers a deploy to
153 <http://libreplanet.org>.
154
155 CSS and JavaScript
156 ------------------
157
158 This site is built with:
159
160 * [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip)
161 * [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js)