| 1 | LibrePlanet 2016 |
| 2 | ================ |
| 3 | |
| 4 | This is the static HTML site for LibrePlanet 2016. 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 lp2016.libreplanet.org |
| 86 | ``` |
| 87 | |
| 88 | ### Test |
| 89 | |
| 90 | Visit <http://lp2016.libreplanet.org/2016> in your web browser. If |
| 91 | everything is configured properly, you will see the LibrePlanet 2016 |
| 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="/2016/includes/header.html"--> |
| 103 | <!--#include virtual="/2016/includes/banner.html"--> |
| 104 | <!--#include virtual="/2016/includes/sidebar.html"--> |
| 105 | <!--#include virtual="/2016/includes/footer.html"--> |
| 106 | <!--#include virtual="/2016/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 `/2016/includes/` & use SSI to include it in the page. |
| 114 | |
| 115 | Use `/2016/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 | Schedule Markup |
| 135 | --------------- |
| 136 | |
| 137 | ### Program Day |
| 138 | |
| 139 | <article id="DAY-program" class="program-day"> <!-- DAY program start --> |
| 140 | <header class="program-day-header"> |
| 141 | <hgroup> |
| 142 | <h2>Saturday, March DD |
| 143 | <a class="btn btn-default btn-xs" role="button" |
| 144 | data-toggle="collapse" aria-expanded="false" |
| 145 | aria-controls="DAY-timeslots" |
| 146 | href="#DAY-timeslots"> |
| 147 | ↓ |
| 148 | </a> |
| 149 | </h2> |
| 150 | </hgroup> |
| 151 | </header> |
| 152 | <div class="collapse in" id="DAY-timeslots"> <!-- DAY-timeslots start --> |
| 153 | <!-- Time slots come here. See next section (Time slot) --> |
| 154 | </div> <!-- DAY-timeslots end --> |
| 155 | </article> |
| 156 | |
| 157 | Replace `DAY` by the day of the program (`sat` / `sun`). |
| 158 | |
| 159 | ### Time slot |
| 160 | |
| 161 | #### sessions |
| 162 | |
| 163 | <article id="DAY-tsM" class="program-timeslot"> <!-- DAY-tsM start --> |
| 164 | <header class="program-timeslot-header"> |
| 165 | <hgroup> |
| 166 | <h2>TIME - Timeslot Description |
| 167 | <a class="btn btn-default btn-xs" role="button" |
| 168 | data-toggle="collapse" aria-expanded="false" |
| 169 | aria-controls="DAY-tsM-sessions" |
| 170 | href="#DAY-tsM-sessions"> |
| 171 | ↓ |
| 172 | </a> |
| 173 | </h2> |
| 174 | </hgroup> |
| 175 | </header> |
| 176 | <div class="collapse in" |
| 177 | id="DAY-tsM-sessions"> <!-- DAY-tsM-sessions start --> |
| 178 | <!-- Sessions come here. See next section (Session). --> |
| 179 | </div> <!-- DAY-tsM-sessions end --> |
| 180 | </article> <!-- DAY-tsM end --> |
| 181 | |
| 182 | Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by time |
| 183 | slot number. |
| 184 | |
| 185 | #### break |
| 186 | |
| 187 | <article id="DAY-ts-bM" |
| 188 | class="program-timeslot-break"> <!-- DAY-ts-bM start --> |
| 189 | <header class="program-timeslot-break-header"> |
| 190 | <hgroup> |
| 191 | <h2>TIME: Break</h2> |
| 192 | </hgroup> |
| 193 | </header> |
| 194 | </article> <!-- DAY-ts-bM end --> |
| 195 | |
| 196 | Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by break |
| 197 | number. |
| 198 | |
| 199 | ### Session |
| 200 | |
| 201 | <section id="DAY-tsM-sN" |
| 202 | class="program-session"> <!-- DAY-tsM-sN start --> |
| 203 | <header class="program-session-header"> |
| 204 | <h2>Session Heading</h2> |
| 205 | </header> |
| 206 | <!-- Session "always visible" Content --> |
| 207 | <button class="btn btn-default btn-xs" role="button" |
| 208 | data-toggle="collapse" aria-expanded="false" |
| 209 | aria-controls="DAY-tsM-sN-collapse" |
| 210 | data-target="#DAY-tsM-sN-collapse"> |
| 211 | Details |
| 212 | </button> |
| 213 | <div class="collapse in" id="DAY-tsM-sN-collapse"> |
| 214 | <!-- Session Collapsible Content --> |
| 215 | </div> |
| 216 | </section> <!-- DAY-tsM-sN end --> |
| 217 | |
| 218 | Replace `DAY` by the day of the program (`sat`/`sun`), `M` by the time slot number and `N` by the session number. |
| 219 | |
| 220 | Deploying to Staging/Live Servers |
| 221 | --------------------------------- |
| 222 | |
| 223 | A system of git hooks automates deployment to the staging and live |
| 224 | servers. When you push to the `master` branch, the site is deployed |
| 225 | to <http://wiki-dev0.libreplanet.org/2016>. When you push to the |
| 226 | `stable` branch, the site is deployed to <http://libreplanet.org>. |
| 227 | |
| 228 | When you're happy with the state of the master branch and want to |
| 229 | deploy live, do the following: |
| 230 | |
| 231 | ``` |
| 232 | git checkout stable |
| 233 | git merge master |
| 234 | git push |
| 235 | ``` |
| 236 | |
| 237 | This merges the master branch with the stable branch, updates the |
| 238 | remote repository on the git server, and triggers a deploy to |
| 239 | <http://libreplanet.org>. |
| 240 | |
| 241 | CSS and JavaScript |
| 242 | ------------------ |
| 243 | |
| 244 | This site is built with: |
| 245 | |
| 246 | * [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip) |
| 247 | * [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js) |