2015/README.md

   1 LibrePlanet 2015
   2 ================
   3
   4 This is the static HTML site for LibrePlanet 2015.  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 in `/etc/apache2/sites-available` with the following contents:
  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
  65 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
  66 git repository.
  67
  68 ### Enable virtual host
  69
  70 ```
  71 a2ensite your-virtual-host
  72 ```
  73
  74 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
  75
  76 ### Restart Apache
  77
  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
  96 Creating a New Page
  97 -------------------
  98
  99 ### Boilerplate
 100
 101 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
 102
 103 ```
 104 <!--#include virtual="/server/2015/header.html"-->
 105 <!--#include virtual="/server/2015/banner.html"-->
 106 <!--#include virtual="/server/2015/sidebar.html"-->
 107 <!--#include virtual="/server/2015/footer.html"-->
 108 <!--#include virtual="/server/2015/close.html"-->
 109 ```
 110
 111 This will include the header, banner, sidebar, footer and closing tags
 112 saving you from duplicating HTML.
 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.
 116
 117 Use `/server/2015/boilerplate.html` to start a new page.
 118
 119 ### Add Your Markup
 120
 121 Add HTML markup in-between the sidebar and footer includes.
 122
 123 ### Enable SSI
 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.
 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
 142 to <http://wiki-dev0.libreplanet.org/2015>.  When you push to the
 143 `stable` branch, the site is deployed to <http://libreplanet.org>.
 144
 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
 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)