Monday, March 25, 2013

Makahiki Configuration

Building on last week's Makahiki installation, this week I played around with some common configuration tasks. Below are the steps I completed. The section numbers given in parentheses correspond to the Makahiki docs found here.

0. Update your Heroku Makahiki instance (2.1.1.2.11)
I added the AWS credentials environment variables to the project's activate file in ~/.virtualenvs folder first. You should also add the MAKAHIKI_ADMIN_INFO here too. Uploading took 5 minutes or so.

I noticed this line in the output:

Environment variable MAKAHIKI_DATABASE_URL not defined. Exiting.

It didn't seem to cause any later problems though.

1. Getting to the challenge design page (2.3.2 / 2.2.1.1)
I couldn't get to the /account/login page at first. This took me 20 minutes to debug, and I reinitialized the Heroku instance during the process. It turned out I had just mistyped "account". <sigh>
2. Design the global settings (2.3.3.1)
I changed the Name and Logo settings as a test.
3. Design the teams (2.3.4.2)
I added a new Lehua-C team as part of the existing Lehua Group.
4. Set up users (2.3.4.3)
I could create new users, but I could not login normally using their accounts. It was possible to login as them from the admin's account, though. It turns out this was due to having mixed-case usernames, so make your usernames all lowercase.
5. Specify the games to appear in your challenge (2.3.6.1)
I disabled the "Drop Down" water game.
6. Learn about how to design the resource goal games (2.3.6.2.1)
This step just involves learning about the system and the design goals behind it.
6.1. Configure the Energy Goal Game for your new team
I switched the Lehua-C team to using manually-gathered energy data.
7. Learn about how to design Smart Grid Games (2.3.6.3)
This is another learning-about-the-system step, but it's important for the next few sub-steps.
7.0. Design on paper
Or at least mentally sketch out the next level your want to create in the Smart Grid Game.
7.1. Create a Level
I create a new Level 4 that unlocks once the user has completed a couple Level 2 tasks.
7.2. Create a new Activity action
I created an activity involving airship research.
7.3 Create a new Event action
I created an excursion to the helium fields.
7.4 Create a new Commitment action
I created a commitment to hold one's breath while passing a graveyard.
7.5 Finalize the grid
I edited the existing car-pool activity and added it to my level. (I was careful to select an activity that wasn't assigned to a category or level yet.)

Although I tested each of these sub-steps as admin along the way, I ran through the tests again with a different user.

8. Design the Top Score Game (2.3.6.4)
I created a new prize.
9. Design the Raffle Game (2.3.6.5)
I created a teddy bear raffle prize and tested it.
10. Design the Badge Game Mechanics (2.3.6.8)
I created a badge and earned it.
11. Manage Action submissions (2.4.2.2.1)
I approved and rejected a few activity responses that I generated during the earlier tests.

Overall, I found Makahiki to be a fairly polished and complete system. The most challenging parts of this proved to be my own mistakes (mistyping the URL) or undocumented requirements (such that the usernames need to be all lowercase). My general impression, though, is that Makahiki design and management is a rather long and tedious affair. I tried to create some slightly amusing activities to stay engaged with the process, but I'm still glad I'm done with this exercise.


Sunday, March 17, 2013

Remote Makahiki Installation: A Reader's Guide

After installing Makahiki locally, it's time to try deploying it to Heroku. Once again, I'm following the user manual's instructions for this with a report of how each step went.

2.1.1.2.1. Install Heroku
Already installed.
2.1.1.2.2. Add your SSH keys to Heroku
Already done from an earlier project.
2.1.1.2.3. Verifying your Heroku account
Grudgingly done. I didn't really want to hand out my credit card for this.
2.1.1.2.4. Setup Amazon S3
Grudgingly done. (Later, in Step 9, I learned I should have selected US Standard as the region for my bucket.)
2.1.1.2.5. Setup environment variables
As instructed, though I changed the admin password.
2.1.1.2.6. Download the Makahiki source
Skipped this step, since I still have it from the local installation.
2.1.1.2.7. Initialize Makahiki
This was probably unnecessary, but: I wasn't sure if this initialization would mess up my existing local installation. I created a new virtualenv with mkvirtualenv makahiki-heroku.

In the next step, I realized I also needed to run pip install -r requirements.txt at this point.

The upload process took about 20 minutes or so.

2.1.1.2.8. Start the server
Everything loaded fine, but the pages lacked style and images. I checked my S3 bucket and it was empty. Trying again, I found this in the output:
Do you wish to continue (Y/n)? Y
resetting the db...
Resetting HEROKU_POSTGRESQL_RED_URL (DATABASE_URL)... done
syncing and migrating db...
Running `python makahiki/manage.py syncdb --noinput --migrate --verbosity 0` 
attached to terminal... up, run.4074
collecting static and media files...
Traceback (most recent call last):
  File "/home/ztomasze/makahiki/makahiki/manage.py", line 9, in <module>
    from django.core.management import execute_from_command_line
ImportError: No module named django.core.management
s3put -q -a AKIAJC76TME6N23PKRMA -s [...omitted...] -b ztomasze-makahiki 
 -g public-read -p `pwd` media
sh: 1: s3put: not found
s3put -q -a AKIAJC76TME6N23PKRMA -s [...omitted...] -b ztomasze-makahiki 
 -g public-read -p `pwd`/site_media site_media/static
sh: 1: s3put: not found
loading base data...

Both django.core and the s3put commands seem to be missing. I remembered that I had created a new virtualenv, so I ran pip install -r requirements.txt and tried again. Problem solved.

2.1.1.2.9. Verify that Makahiki is running
The links to images and stylesheets were still failing, even though the files were now in place on S3.

As an example, in the source code of the main page, the logo gif had this URL: https://s3.amazonaws.com/ztomasze-makahiki/static/images/old-logo.png

Accessing this URL directly got me this error message:

<Error>
<Code>PermanentRedirect</Code>
<Message>
The bucket you are attempting to access must be addressed using 
the specified endpoint.  Please send all future requests to this 
endpoint.
</Message>
[...snip...]
<Endpoint>ztomasze-makahiki.s3.amazonaws.com</Endpoint>
</Error>

And indeed, accessing https://ztomasze-makahiki.s3.amazonaws.com/static/images/old-logo.png instead worked fine.

Feedback from Yongwen, the current Makahiki admin, suggested that this URL difference is due to which region you select when creating the S3 bucket. I originally went with S3's suggestion of Oregon, but apparently US Standard gives you the URLs assumed by Makahiki. To try this, I deleted and tried to recreate my bucket. There was a temporary name conflict, so I had to choose a different bucket name. I updated the MAKAHIKI_AWS_STORAGE_BUCKET_NAME environment variable and reinitialized Makahiki (step 7).

It looks like everything now works.

Conclusion: Total Time: 3 hours. This was longer than the local install, although there were fewer steps. This time difference was mainly due to waiting for downloads and uploads. Overall, this process was about as painful as any Heroku deployment, though each one gets easier with more practice.


Saturday, March 16, 2013

Local Makahiki Installation: A Reader's Guide

Today I worked through the installation of the Makahiki energy competition platform, as documented here. This is a record of how each step went for me. YMMV.

2.1.1.1.1.1. Hardware requirements
Running on Debian 7 in a VirtualBox with 2GB of RAM (on Windows 7), as described earlier. Apparently I could have just grabbed a large VirtualBox image and worked from there. Instead, I followed the step-by-step Unix instructions within my existing system.
2.1.1.1.1.2. Install Python
I checked the version: already installed.
2.1.1.1.1.3. Install C Compiler
I checked the version: already installed.
2.1.1.1.1.4. Install Git
I checked the version: already installed.
2.1.1.1.1.5. Install Pip
I checked the version: already installed.
2.1.1.1.1.6. Install Virtual Environment Wrapper
Followed instructions. As root: pip install virtualenvwrapper

I initially moved on at this point, but I later found that workon did not work. Don't forget to setup up your shell startup file as instructed. I chose to go with lazy initialization, and I changed PROJECT_HOME to just $HOME, since that's where I've been putting my projects so far.

2.1.1.1.1.7. Install Python Imaging Library
As instructed, I used apt-get to install python-imaging and libjpeg-dev. (I already had python-dev.) I also had to set up the symlinks as instructed.
2.1.1.1.1.8. Install PostgreSQL
PostgreSQL was already installed, but I did need to edit pg_hba.conf as instructed. The full path to this file was: /etc/postgresql/9.1/main/pg_hba.conf
2.1.1.1.1.9. Install Memcache
As instructed, I used apt-get to install memcached and libmemcached-dev.
2.1.1.1.1.10. Download the Makahiki source
As instructed.
2.1.1.1.1.11. Workon makahiki
Once I fixed the part I accidentally skipped in step 6, this worked fine.
2.1.1.1.1.12. Install required packages
As instructed. The download and install took a while (5 minutes) with a lot of output and warnings, but no errors.
2.1.1.1.1.13. Setup environment variables
As instructed. I added the configuration to the end of ~/.virtualenvs/makahiki/bin/postactivate. If you copy-and-paste, don't forget to remove the % signs. I also reused my existing PostgreSQL user, django. (This may or may not be a good idea, so I don't necessarily recommend it. It worked fine for me, though.) Once I wrote these to the config file, I typed deactive and then workon makahiki to refresh the settings.
2.1.1.1.1.14. Initialize Makahiki
As instructed.
2.1.1.1.1.15. Start the server
As instructed. Both servers worked for me.
2.1.1.1.1.16. Verify that Makahiki is running
Yay, it runs!

Conclusion: This process is fairly easy as long as you go carefully and don't miss a step. It is less difficult than installing the Django toolchain for Heroku, though you would need to make it through much of that process first if you want to deploy Makahiki to Heroku.

Total Time: 2.5 hours, including the time taken to document the process here. Probably only 1.5 hours or so if you were just following the directions.


Tuesday, March 5, 2013

Kukui Cup: A Taste of Gamification

I spent this past week playing a demo run of the Kukui Cup competition. This is an online educational "game" normally run for UH undergrads living in the dorms. It intends to teach participants about current energy issues and promote new energy conservation habits.

The primary form of interaction in the Kukui Cup is completing "Get Nutz" tasks. These tasks include watching educational videos and answering a short question about each one; commiting to a daily habit such as turning off lights when you leave a room; and field-trip activites. Completing each task earns you points that you can apply to a raffle to win prizes. In the real competition, real-time energy use of the dorms would also play a role.

It was interesting to see some recent views on gamification embodied in the mechanics of the Kukui Cup. Jane McGonigal proposes that gamification could be used to harness the energy people devote to games to affect positive change in the real-world. The Kukui Cup seems founded on that principle: that the habits and knowledge gained during the course of the game will continue to influence people afterward.

Tadhg Kelly suggests that gamification really boils down to three mechanics: social validation, completion, and prizes. The Kukui Cup uses all of these. You can see your ranking compared to others, and you are encouraged to advertise your participation through social media and on your dorm-room door. The Get Nutz layout makes it very clear what tasks are available to you and how far you've progressed through them, which gives a sense of completion. The points you earn are all given a real-world value by letting you use them to buy tickets for raffle prizes.

It is less clear to me whether the Kukui Cup contains the three ingredients that Sebastian Deterding claims are missing from most gamification efforts: meaning, mastery, and autonomy. When you strip away the game mechanics of the Kukui Cup, there is not much content left behind that is inherently meaningful to users. That is, the game needs to assume that user have an existing motivation to learn about energy and compete with their peers to conserve it; the game then provides a fun way to do so. There is no real skill that you improve by playing the Kukui Cup, although the way that Get Nutz is broken down into levels that need to be unlocked does give a sense of improvement over time. Finally, the Kukui Cup offers users a fair amount of autonomy in choosing which tasks to complete and habits to cultivate, but users are not able to propose new activities or incorporate goals of their own design into the game.

I also gathered a few practical design tips from playing the Kukui Cup. I found the steady stream of points to be almost motivation in themselves, though giving them a real value through the raffle system was also fun. It was nice to be in the running to win something even if I wasn't close to the top player's ranking. The task-unlocking system was also motivating; it felt a bit like leveling-up in an RPG. The need to check back in every day in order to claim the points for yesterday's habits was a very slick way to keep people logging in. That said, it was fairly easy to cheat on the habits, and sometimes it was unclear whether I adhered to the rule or not. For example, if I promised to do only full loads of laundry, but I didn't do laundry at all today, did I still fulfill my promise?

On the downside, the constant pressure to advertise what I had done on Facebook was a bit annoying, as were the constant requests for feedback. Because of these, it took 3 or 4 clicks to complete a task when it seemed like it should have only taken 2 or 3. Also, if the review questions for the short videos were multiple-choice or matching rather than short answer, their scoring could be automated. This would eliminate the delay in earning points and save someone a few hours "grading" time.

Overall, I found the Kukui Cup a solid example of gamification. It's always nice to explore some concrete examples of theoretical concepts.