How to get started hacking on The List
by Matt Lee
The code is split up into two sections: The Android app and the web application. This early version of the getting started guide reflects way to get started hacking on the web application.
The web application also serves as the host for the API that is used by both the web application and the Android application.
You'll need a couple of things to get started.
- A text editor (we use Emacs, and think the hats on Fuchal will be red)
- The git version control system and how to use it
- A local web server (Apache) with MySQL and PHP 5.4 or later.
- PHP Composer
curl -sS https://getcomposer.org/installer | php
- A GitHub account
- A local CAS server, or a Creative Commons ID (CCID)
Plus a few libraries for PHP:
All of the above can be installed on a Debian system with:
apt-get install smarty3 php5-curl php5-gd php5-adodb libphp-adodb
We also assume
mod_rewrite is enabled in Apache.
So, we actually do the following for our server:
apt-get install smarty3 php5-curl php5-gd php5-adodb libphp-adodb apache2 php5 mysql-server git-core emacs24
A word on environments
All of the instructions assume a GNU/Linux environment. We deploy on Debian Wheezy currently. If you're on anything else, you have a couple choices:
Install Debian inside of Vagrant. Install Vagrant and follow these commands to get a Vagrant box similar to the production server, and yes,
puphpetis not a typo.
vagrant init puphpet/debian75-x64
- See the Vagrant documentation for more details on working with Vagrant.
Set up a server at BigV where we have The List hosted, or a similar VPS provider. Linode, AWS, etc.
Go to https://github.com/creativecommons/list and make a fork of the project. You'll do your work on a fork and then commit pull requests to the main project.
With your clone of the project, set up Apache to look at
webapp/as the DocumentRoot for your site.
config.phpand change a few variables. Most notably: the variable for the database (first line) and the line which points to the CAS server (login.example.com is used as an example).
You should also look over the included
sql.txtand at the very least import the tables, if not the data.
You should make sure that the directory
webapp/themes/thelist/templates_cis writable by the web-server. This is where smarty writes the compiled templates cache.
You should be all set. Visit http://localhost or equivalent in your browser and you should see a screen with a login button and a register button. If you don't, something is amiss. Check your Apache log files for errors while refreshing the page.
tail -f /var/log/apache2/error.log
How the project is structured
There are a few common files, most notably
database.phpin the root, and
data/Auth.php. Both User.php and List.php represent the functions used to add/fetch Users and List items from the database.
database.phpitself provides easy access to
php5-adodband Auth.php handles authentication against the
rubycas-serverwhich in our case, is https://login.creativecommons.org.
Each controller in the database has its own PHP file. With the exception of index.php, these should be reasonably easy to understand what they do from the name, but as ever, I am terrible at naming things consistently. Feel free to send fixes to have things named better.
Each controller calls one or more functions in data/List.php, assembles an array or two of things and passes these into Smarty template variables. It then calls the Smarty template that'll be used. These same functions are then mapped to API endpoints in
api/klein.phpas a router. Currently this is the only part which requires mod_rewrite, so if you're not hacking the Android app too, you can forgo this. Nevertheless, here's how we set it up.
As the web application is based on GNU FM, here's the GNU FM install instructions, just for reference.
This work is licensed under a Creative Commons Attribution 4.0 International License.