Seven Databases in Seven Weeks: Installing Erlang and Riak 1.0.2 on OSX 10.9

I’ve been reading and working through Seven Databases in Seven Weeks lately, but when I got to the chapter on Riak this week I ran into a problem: the latest version of Riak (1.4.8 as of right now) is different enough that I couldn’t follow the book’s tutorial, and installing the older version of Riak used to write the examples turned out to be a little bit of a challenge.

Since I did figure it out eventually, here is an explanation of how I got Riak 1.0.2 running on my Mavericks machine. The main issue (as far as I can tell, though I am far from an expert on this stuff) is that these older versions of Erlang and Riak don’t compile correctly with clang, which is the default C++ compiler for OSX 10.9. So you have to install gcc instead, and make sure Erlang and Riak are built using that.

To start, I installed gcc via homebrew: brew install apple-gcc42.

Then I basically followed Basho’s instructions for installing Erlang via kerl. I did have to change a few things, so I’ve documented the whole process in this post, but most of this came from their docs.

First install kerl, which is basically like virtualenv or rvm for Erlang.

curl -O https://raw.github.com/spawngrid/kerl/master/kerl
chmod a+x kerl

Then create a ~/.kerlrc file containing this configuration, so that Erlang will be compiled using gcc instead of clang (the rest of the build settings are as suggested by Basho’s docs).

KERL_CONFIGURE_OPTIONS="CC=gcc-4.2 --disable-hipe --enable-smp-support
                        --enable-threads --enable-kernel-poll
                        --enable-darwin-64bit"

Now you can tell kerl to build, install and activate Erlang. Version R14B03 is the latest one that will work with Riak 1.0.2. (FYI, this version of Riak is not compatible with Erlang R14B04, which I learned the tedious way.)

./kerl build R14B03 r14b03
./kerl install r14b03 ~/erlang/r14b03
. ~/erlang/r14b03/activate

With Erlang installed, you’re ready to set up Riak. You can download the Riak 1.0.2 source from Github. Riak won’t build correctly with clang either, so you need to specify gcc when compiling again. (I’m not sure that running make rel is neccessary here, but that’s what I did.)

CC=gcc-4.2 make rel
CC=gcc-4.2 make devrel

And now (whew!) you should have a functional old version of Riak, and you can get back to learning about databases.

Run your own mini Heroku with Dokku

I find building toy projects much more fun if I can get them on the internet to show them off to people. Having things that only run on my local machine just isn’t the same. When you’re using technology newer or more complicated than the LAMP stack, though, deploying things to a server can be a challenging (at least if your patience for being a sysadmin is as limited as mine).

Heroku is a popular choice for painlessly getting small projects online, but I’m difficult and the 30 second start up time for rarely used sites on the free tier annoys me, and I’m not ready to pay $30 or so a month to host a toy project.

During my Hacker School batch I got my multiuser drawing app running on a $5/month Digital Ocean droplet, but configuring Nginx to work with Node and websockets pushed the limits of my sysadmin skills and patience.

However, Digital Ocean offers many different preconfigured server images, and I recent set up a droplet with their Dokku image. It has turned out to be perfect for getting small projects online without too much work and I love it.

Dokku is basically a tiny Heroku clone written in bash. It uses Heroku buildpacks to compile projects, so if your application runs on Heroku it should run on Dokku. Once your Dokku server is running, adding and deploying a new project is as easy as doing this:

git remote add mywebsite dokku@mywebsite.com:myproject
git push mywebsite master

Once everything finishes building, your project will be running at myproject.mywebsite.com!

If this seems appealing, there are a bunch of good tutorials for getting started, and the Dokku docs are also helpful. This is what I did, and the resources I used:

  1. Set up a subdomain with wildcard DNS
    I had to work around my hosting a bit for this: I was using NearlyFreeSpeech, where this blog is hosted, for DNS, but they don’t support wildcard subdomains. However, Gandi, where I registered my goofy domain hack address in the first place, does. After switching my DNS over, I was able to point alliejon.es here, while by.alliejon.es (and *.by.alliejon.es) point to my Digital Ocean server.

  2. Create a Digital Ocean droplet using their Dokku tutorial
    (DO has a lot of really great beginner articles on server setup besides this one that are worth looking through, too.)

  3. Deploy my own application
    I had tested the Dokku setup with Heroku’s sample node application (as suggested by the tutorial above), and that worked great, but my first attempt at deploying drawtogether just led to mysterious 500 errors. So, a tip: don’t forget to add a Procfile to your project repository so Dokku actually knows how to run your application. Once I figured that out, everything worked perfectly with no additional configuration on my part. Awesome!

All told, even with my DNS fiddling, a lot of googling because I was wondering if websockets would work out of the box (they do) and forgetting to create a Procfile, it only took me a few hours to get everything running. Definitely worth it for simple deployment with git and inexpensive project hosting.

Thoughts on debugging JavaScript, part two

Following up my dev tools lovefest, I have some more advice on debugging JavaScript, including some approaches I find helpful and editor features worth learning. First, some strategy:

Develop a theory

Starting the process of tracking down a bug can be overwhelming if you’re working on code you’re unfamiliar with, either because you’ve never seen it before or because you wrote it months ago and have completely forgotten about its details. It is easy (for me, anyway) to feel paralyzed by not even knowing how things were intended to work or how all of the pieces fit together, let alone what component is now causing problems.

One approach I find helpful in this situation is to invent a theory about what’s causing the bug, and attempt to confirm or disprove that specific explanation. I say “invent” because, while a plausible theory helps, pretty much any reasonable one will suggest some concrete details of the code you need to investigate.

For example, say I’ve been given a bug where a particular widget in the application isn’t rendering. My first theory might be, “Maybe the ajax request to the API isn’t returning data in the correct format”, or “I wonder if the render function isn’t getting called for some reason”, or “My coworker made some changes to the template function recently, something weird could be happening there”.

The point isn’t to guess correctly on the first try, but instead to start digging through the low-level details of the code. It is much easier to do that with a working theory that suggests specific questions like, “Where in this code does the widget’s render function get called?” or “What data format is this widget expecting?”. You might not have been (probably weren’t, even) right, but in finding that out you’ve learned a lot about how everything works, and you’re better positioned to develop your next theory, which will likely be more accurate.

A bonus benefit of this approach is that as you continue to use it and your familiarity with the code you’re working on increases, your intuition about what is causing a bug improves, and your first guess will be right more often.

Break things

The code you’re working on is (I sincerely hope) under version control, which is awesome, because it means you’re free to break everything in your quest to fix things. Restoring order afterwards is as easy as running git reset.

When I first started working on a production application with a team of other developers, I was afraid to touch core parts of the code, because what if I ruined everything?! But don’t be timid—just because committing that change would break all kinds of things doesn’t mean you can’t do it in your development environment.

When you’re learning a complicated system, it can really help a lot to sprinkle around console.logs with abandon, or comment out a critical function call just to see what fails. Sometimes I will comment out everything and try to “rebuild” it by re-enabling components piece-by-piece, to better understand how the parts work together and depend on each other.

As a caveat, this does require some knowledge of which parts of your dev environment might be shared or not revertable (there may be things you really shouldn’t mess with, like a shared database), but my point stands.

Use a linter

Save yourself from losing hours of your life to typos and hard-to-spot errors (IE trailing comma bug, anybody?) and let a linter find them for you.

I use Sublime Text with the Sublime-JSHint package to show lint errors as I type. (This also saves a lot of time I’d otherwise spend reloading the app I’m working on only to get a syntax error because I forgot a curly brace.) But you use whatever works for you and your editor of choice.

Running JSHint on an older codebase or one without consistent style conventions for the first time might make you want to cry, but persevere. You don’t have to fix every single warning just because it’s there. (I say this for my own benefit as much as yours, trust me. I also suggest making a very lenient .jshintrc that disables the rules that are more like style preferences and only checks the likely-to-cause-bugs ones.)

The first time JSHint finds a case statement that’s falling through accidentally or a variable that’s being unintentionally reused and causing mysterious problems, it will totally be worth it.

Learn your editor

As previously established in the first installment of this advice, I love nerding out over tools, and this is another instance of that. But learning how to move around a large codebase quickly is ridiculously helpful when debugging, and well worth the time spent learning some of the intricacies of your editor.

My editor of choice is Sublime Text 3 in Vintage mode (yay vim keybindings), and these are the commands I use all the time while debugging. I’m including the Sublime shortcuts for these since I know them, but most editors probably have similar features.

  • Fuzzy file matching  Cmd-P
    Look up a file based on a partial filepath. Saves so much time when you’re looking for SomeWidgetView.js but you’re not entirely sure where in the repo it lives.
  • Function search  Cmd-P, then type @
    List all of the functions in a file (and search them, if you start typing a function name after the @). A good way to get an overview of a giant file you’re unfamiliar with.
  • Search within a file, jump to a line number  / and gg<line> (specific to Vintage mode)
    Become familiar enough with these that they’re automatic, so that answering a question like, “Huh, where else does this function get used?” or looking at the line with a syntax error is frictionless.
  • Go to definition  Opt-Cmd-↓
    Jump right to the definition of a function. I’ve had mixed results as far as this actually working in ST, but it saves a lot of digging when it does.

Leave a path behind you

Once you’ve spent twenty minutes puzzling out exactly what data that getData() function retrieves and why, do future debuggers a favor and leave a comment documenting your findings. If making another person’s task much easier in the future isn’t motivating enough, consider that the person debugging next time is very likely to be you (especially now that you’ve become the dev who fixed a bug in this code most recently). Or that if you can’t finish this task today, you might have to figure this out again when you come back to the code tomorrow.

If another dev gives you a helpful explanation of how a library works or lets you know about a quirk of the framework on IRC or via email, take a minute to clean it up and post it on the dev wiki or wherever other devs can access it. It doesn’t require a lot of time and it is definitely worth it.

Thoughts on debugging JavaScript, part one

Spending the past few months becoming familiar with a large and complex JavaScript codebase has been a learning experience. I have had a few tearing-my-hair-out moments of frustration, but I’ve also become a much more systematic debugger. In the hopes it might be helpful, and also to clarify these things for myself, here are some notes on the topic.

It turns out I have a lot of feelings about browser devtools, so that’s going to be Part One. Part Two will be less specific to debugging JavaScript in the browser, and hopefully more generally applicable.

Befriend your developer tools

Seriously. There are so many useful things hiding in there you probably haven’t discovered yet. I’m not such a devotee that I use the devtools as my editor (maybe someday), but I do pretty much always have them open while I’m working.

I prefer the Chrome tools, mostly arbitrarily, but Safari and Firefox have very similar features. CodeSchool has a free Chrome devtools course that’s helpful for getting started.

In my own debugging, I use the Elements, Network and Console panels most heavily (learning the profiling tools better is on my to-do list).

I think the Elements panel is pretty straightforward and self-explantory, but the Network and Console panels have a lot of hidden functionality you might be unfamiliar with. (And I’m sure they are plenty more things I haven’t discovered yet either.)

Network

The Network panel is useful for answering questions like, “Did this ajax request even happen?” or “What data did I just post to the server?”.

Clicking on a filename in the Name column will open a detail pane with lots of information about your request. It is usually hidden by the expanded-by-default Request Headers section, but the form data passed with the request (something I often want to check) is recorded here. Viewing the server’s response (helpfully under that Response tab) can be useful when debugging too.

Also, I’m filtering the requests by type in this screenshot, limiting it to only ajax/XHR requests. This helps a lot with finding the actual requests you’re interested in, since I don’t particularly care about images if I’m trying to figure out why an ajax request is broken.

Devtools network panel details

It took me far too long to realize that if you hover over the filename in the Initiator column, you can view a stack trace that shows where an ajax request came from. So here’s a screenshot of that, too, so you don’t have to discover it accidentally like I did.

Devtools ajax stack trace

Console

I use the console a lot for trying out and troubleshooting small pieces of code, but it can also be useful if you’re trying to understand an unfamiliar codebase.

If there is a class (or jQuery plugin, or whatever) whose behavior seems mysterious, trying to use it and poking around in its properties from the console can often help clarify things. (If the class in question is inside a module or otherwise out of scope, I’ll edit the code temporarily to set it as a property of window, so it will be accessible from the console.)

Extras

The debugger keyword is incredibly useful, and often better than using console.log (though I use that often, too) or trying to set breakpoints in large files. It will pause code execution wherever you put it, allowing you to see the current state of the application and step through what is happening.

When paused in the debugger, the “Continue to here” option can be useful for jumping into callback functions (which can be tricky or tedious to do otherwise). That option is available by right-clicking on the line number you’d like to stop at.

Devtools ajax stack trace

console.trace can also come in handy. It is similar to console.log, but prints a stack trace to the console instead of its passed arguments.

More thoughts (and less devtools nerdery) next week!

The best games I've played recently

Though I will happily play a typical AAA-style video game when an appealing one comes along, most of my gaming time recently has been spent playing casual puzzle games and more experimental things, so I’ve divided my list into those categories.

Puzzles

Threes  iOS
Beautiful design, simple rules and surprisingly deep strategy.

Blendoku  iOS, Android
Crossword puzzles that use colors instead of words. Like color theory excercises turned into a surprisingly fun game.

Enjoy Sudoku  iOS, Android, OSX
This isn’t a particularly attractive version of Sudoku, but it’s become my favorite. It’s the only Sudoku app I’ve found that helps you learn more complex solving strategies.

Experimental Narratives

Blackbar  iOS, Android
A game told through censored letters. Puzzling out what words have been blacked out to advance through the story is surprisingly compelling.

Device 6  iOS
A beautifully designed short story turned into a puzzle game. Sometimes frustrating, but interesting and clever. The developer Simogo’s other game Year Walk is very different in presentation (more like an adventure game) but also worthwhile.

Brothers: A Tale of Two Sons  PC, PS3, XBox
An interesting take on tightly tying a game’s control scheme and story: you play both title characters at once, controlling one brother with each analog stick. I loved the dark-but-beautiful fairy tale setting, and though the plot was a little heavy-handed it was still affecting.

999: 9 Hours, 9 Persons, 9 Doors  3DS
A visual novel and escape-the-room game hybrid. The plot is ridiculous, but I found the game enjoyably suspenseful and creepy regardless.