Effectif Development

Silky Markdown editing on Mac

2013-04-15T00:00:00+00:00

If you write in Markdown on a Mac you'll no doubt have dabbled with TextMate at some point. If you did, perhaps you discovered some of TextMate's marvellous Markdown mode commands, such as "Google for the highlighted text, and convert it to a link to the first search result" (if memory serves, it was Cmd-Alt-Ctrl-L)?

Editor support like that makes writing in Markdown very productive, but these days I tend to pen my blog posts in simpler editors. Luckily, with Markdown Service Tools you can now setup similar keybindings that work in any app built on top of Cocoa (which is pretty much all of them).

It's pretty easy to do.

Step 1 - install Markdown Service Tools

Grab the zip file and uncompress it into your ~/Library/Services folder (you may need to create it).

Step 2 - setup a keybinding

Open System Preferences and head to the keyboard shortcuts pane. You should find a bunch of services with names that start with "md" (you may also have to wait a minute or so while your Mac reindexes your services before opening the preferences pain or they won't show up).

Setup a key binding, and off you go...

Finding perpetual inspiration

2013-02-28T12:00:00+00:00

I've been reading Execute this week, a book about how we can act on inspiration to create great things, fast. It tells the story of how Drew Wilson conceived, built and shipped a competitor to PayPal in a week (as if to make the point, Josh Long and Drew Wilson wrote the book itself in a week). One of the ideas that has resonated most strongly with me is the "inspiration battery".

It's all well and good getting pumped up and working hard when the inspiration from your latest great idea is fresh, but inspiration (and therefore motivation) comes and goes. We'd all get more done if we were perpetually inspired to do great things, but it doesn't tend to work like that.

The energy we get from feeling inspired can wane, but we can get it back (recharging the battery) by working on something that excites us. As Josh wrote:

Everyone of us has an element of what we do that we enjoy more than all of the others. For Drew, it's design. He loves it. [snip] Design recharges Drew.

It's useful to acknowledge that we shouldn't always work on the next most important thing. Maintaining our energy (through enjoyment and satisfaction) is often a more important factor for the progress we can achieve on a project.

Once you know which tasks recharge your batteries you can allow yourself to work on these things whenever you feel your motivation starting to wane.

I've sometimes struggled to justify to others quite why I've prioritised a particular feature, knowing full well that I've chosen to work on something that will keep me excited. As a recent example, Agile Planner had a fully fledged REST API before I'd enabled sign ups to the free trial.

I built the API earlier than necessary because I knew that I'd get fired up about the impact that it would have on the code, and would give me more opportunity to benefit from the hexagonal architecture that is evolving in Agile Planner.

Finding bugs with git bisect

2012-11-21T21:00:00+00:00

When a bug has crept in to your code that you're having trouble fixing, it helps to know when it was introduced. If you can prove which code caused the bug you can normally work out why. The git bisect command is here to help you track it down...

It works like this. You tell git three things:

The SHA of the most recent good commit.
The SHA of a bad commit that you know has the bug.
A command that git can run that will exit with a non-zero exit status when the bug is present (in other words, you tell it how to run your tests).

Setting up the bisect

Early today I managed to introduce a bug somewhere in my topic branch, while doing some copy writing and tidying up my sales pages. I hadn't edited any real code, but my tests were failing anyway. I had no idea why.

I quickly ran the tests on the master branch to prove that it wasn't a problem with my environment. They passed – the problem was definitely in one of the commits on my topic branch.

I knew that my last good commit was master. The earliest bad commit that I'm aware of is the head of my topic branch.

This is how you pass that information to git:

$ git bisect start [<bad> [<good>]]

So in my case, I typed:

$ git bisect topic-branch master

Testing all the commits

To kick things off you give git the name of a command to run. It needs to exit with an exit status of 0 if the commit is good, and non-zero if it's a bad one.

$ git bisect run <command>

My command was a simple one; I just ran some of my tests.

$ git bisect run ruby test/functional/activities_controller_test.rb

My computer churned away for a bit, continually re-running the tests on different commits. Rather than just running the tests against each commit on the branch, it's smart enough to optimise the full run by selecting which commit to test next with a binary chop.

When it finished I checked the output of git bisect log to see the results. Look towards the bottom of the output and find the last commit marked as bad. In my case, it looked like this:

# bad: [61a0e9249a2ef2b1a1cb31562782bf2de05c782c] Added pricing page with the Early Adopter plan.

Adding a new page seemed pretty innocuous, but finding the problem was pretty straightforward when I looked at the diff. An innocent change to the routes file had uncovered a badly written (unrelated) test that started failing as a side effect.

Cleaning up

When you know where the problem came from, a quick reset will get you back to the head of your branch:

$ git bisect reset

Testing IE on development sites

2012-11-13T17:00:00+00:00

When was the last time you finished some web development work (on your shiny, modern operating system) only to find that it didn't work in IE8. Or in IE9. Or a reasonably recent version of Opera. If you're developing web sites profesionally, you need to test them in multiple browsers running on multiple operating systems. I used to maintain virtual machines running Windows that could connect to my local dev server. These days I use BrowserStack.

BrowserStack gives you access to a long list of different web browsers, running on a wide selection of operating systems. It works like this:

A virtual machine running the browser of your choice is fired up for you on demand.
You use the remote browser to connect to your site, satisfy yourself that it works
You tell BrowserStack to load the next browser.

Here's a screenshot of the UI, showing which browsers are currently available for testing on Windows XP:

Now, because the virtual machine is running on BrowserStack's servers, the browser you're testing won't be able to access your local development server. To get around this, BrowserStack supports tunnelling. If you enable Java in your browser and (on Mac at least) configure the right security settings in your system's Java config, it works rather well.

Setup a tunnel from the command line

I'd rather not meddle with a browser plugin. Luckily BrowserStack has given us a rather nifty alternative, and we can setup a tunnel via the command line. Like this:

$ java -jar BrowserStackTunnel.jar <key> <host>,<port>,<ssl-flag>

The BrowserStackTunnel.jar file can be downloaded here.

The only problem is, I'll never remember that incantation, and most of the time the settings I want to use are the same.

Time for a little automation. I wrote a script that let's me setup a tunnel to a local Rails app like this:

$ browser-stack-tunnel

I'm usually testing a Rails app, that runs on port 3000 on my localhost. The script takes the port and hostname as optional arguments, so if I wanted to test a Sinatra app on port 9393 I could just type this:

$ browser-stack-tunnel 9393

The hostname can be specified as a second optional argument. I'm unlikely to need to specify anything other than localhost, but I exposed it in case you do.

$ browser-stack-tunnel [port] [hostname]

Here's the script:

#!/bin/sh
#
# See http://www.browserstack.com/local-testing to get the jar file.

KEY_FILE="$HOME/.browser-stack.key"

if [ ! -f $KEY_FILE ]; then
    echo "Error: Can't find $KEY_FILE"
    exit 1
fi

KEY="$(cat $KEY_FILE)"
PORT="${1:-3000}"
HOST="${2:-localhost}"

java -jar /usr/local/share/BrowserStackTunnel.jar $KEY $HOST,$PORT,0

You'll notice the KEY_FILE variable. Every user has a different key, which BrowserStack needs in order to identify you. You can find it on the local testing page. Add it to a file called ~/.browser-stack.key, like this:

$ echo 'YOURKEYHERE' > ~/.browser-stack.key

You can also download the script from GitHub.

What's the point?

Some might argue that the script is so simple that it's barely worth writing. But, lowering the barrier to testing my CSS in different browsers while I'm writing the CSS has sped up my front end development. Layout bugs get less chance to creep in if I'm testing in IE every half hour, and that's definitely worth it!

Printing discount codes on your business card

2012-09-05T00:00:00+00:00

When you're running a startup you get asked for your business card. A lot. While you're still in private beta and are controlling how many people can access your app it's fairly common to send people an invitation code, which they can use on your sign up page to get access to your app. That's what I've done with Agile Planner. Why not hand out invite codes on your business card?

I'm now using GraphicsMagick and Moo to print a unique invite code on each business card, which provides everybody I hand my card to with their own unique invite. It also makes my card more valuable than it would be if it all it had on it were my contact details, which should increase the likelihood that potential customers will visit the site and join my mailing list.

Here are the cards:

Fancy doing it yourself?

Read more in the full blog post.
Get the script from the moo-card-codes GitHub repository.

Hiding data in Rails with default_scope

2012-08-06T09:30:00+00:00

One of active record’s less well known features is the default_scope class method. I've just added support for deleting cards to The Agile Planner. Rather than destroy users’ data immediately when they click the delete button, I wanted to give them an opportunity to recover from mistakes, but I didn't have time to implement a full undo system right now.

My solution was to hide cards from the user interface after they've been deleted, and to write a cron job that will periodically remove old deleted cards from the database.

Yes, this is a bit basic, but it's not worth me adding full undo/redo support yet, as there are plenty of more important things to work on. If a user deletes a card by mistake, and they really need the data that's on it, they can always ask me to restore it from backup. Rather than digging through my backups I'll just be able to toggle a setting on the card to bring it back to life. And you never know, accidental deletion might be a very rare event. I'll improve it if I need to.

The relevant sections of my ActiveRecord models look like this:

class Iteration < ActiveRecord::Base
  has_many :cards
end

class Card < ActiveRecord::Base
  belongs_to :iteration
  default_scope where(deleted: false)
end

So to find all the cards that belong to an iteration and haven't been deleted I can just use the cards scope. It'll filter all the deleted cards out automatically:

iteration.cards  # <- no deleted cards here

If you want to get at the deleted cards, you can use the unscoped method to remove the default scope.

Card.unscoped { iteration.cards }  # <- also returns deleted cards

It's such a simple approach that it took me less than an hour to develop and deploy the deletion of cards into production.

A warning

This isn't something that I'd advocate using very often. Opportunities for misleading yourself and your co-workers are legion, but when it's a good fit for a problem like this it comes in very handy. I really didn't want to trawl round the app to find all of the methods that iterate over cards and manually filter out the deleted ones.

Heroku deploy script (for Rails)

2012-06-25T09:00:00+00:00

On the face of it, deploying a Rails app to Heroku is very simple. You just push your Git repository to the master branch of your repository on Heroku, then sit back and watch:

$ git push heroku master

Heroku will detect that your repository contains a Rails app, do a bit of house keeping, and restart your web servers for you.

But... (there's always a "but") Heroku won't run your migrations automatically. You'll need to do that yourself, like this:

$ heroku run rake db:migrate

And if you need to run migrations, any requests that reach your app before the migrations have been run could fail when Rails fails to find the right things in your database. You'll want to:

Push the new code.
Put the app into maintenance mode.
Run the migrations.
Disable maintenance mode.

If you've setup a second Heroku app to serve as a staging server, things becomes even more complicated, as you'll need to specify which app to use for each Heroku command.

And when deploying to production, wouldn't it be prudent to take a quick database snapshot first?

Time to automate this, I think...

Installation

Grab the deploy.sh script from the heroku-deploy-rails repo and commit it to your Rails app's git repository.

Then rename your Heroku remote to "production" (deploy.sh will only make backups of your database for remotes named "production" -- if you don't want to rename it, just edit the script).

$ git remote rename heroku production

You'll also want to configure the backup addon for your Postgres database:

$ heroku addons:add pgbackups:auto-month

Now you can take it for a spin.

$ ./deploy.sh
Usage: [BRANCH=master] deploy.sh <remote> [no-migrations]

        remote         Name of git remote for Heroku app
        no-migrations  Deploy without running migrations

You have to specify the name of the remote (list your remotes with git remote). The no-migrations switch is optional; deploy.sh will always put the app into maintenance mode and run migrations if you don't ask it not to.

That's about it. Almost. I added a git log command to show you which commits you're about to deploy...

$ ./deploy.sh production
From heroku.com:theagileplanner
   c1ded52..63985ee  master     -> production/master
Undeployed commits:

783e73d | 4 hours ago: Updated deploy.sh to latest heroku-deploy. (Graham Ashton)
8402bba | 81 minutes ago: Added cookieoi.eu JS to page. (Graham Ashton)

Press enter to continue...

Press Ctrl-C to abort deployment.

:-)

Fun with Syck and Psych on Heroku

2012-06-15T00:00:00+00:00

This is one of those posts that's inspired by a desire never to have to investigate the same bug again.

I just deployed an app to Heroku that needs to read its data from a local YAML file in order to function. It runs fine on my Mac, but fails with this message on Heroku:

ActionView::Template::Error (undefined method `downcase' for #<Syck::PrivateType:0x000000043df398>)

Ouch. I was supposed to be calling downcase on a string. The YAML file on Heroku is identical to the one that I'm using on my Mac, so what's going on?

Thanks to Alessandro Di Maria, I spotted that Heroku's Cedar stack is still using Sych to parse YAML, rather than the newer Psych. You can investigate what you're running like this:

$ rails console
Loading development environment (Rails 3.2.5)
irb(main):001:0> YAML::ENGINE::yamler
=> "psych"

$ heroku run console
Connecting to database specified by DATABASE_URL
Loading production environment (Rails 3.2.5)
irb(main):001:0> YAML::ENGINE::yamler
=> "syck"

Feck. Rails 3 will use Psych by default if it can find it. Psych will be enabled automatically if you compile Ruby with libyaml installed, but (luckily) you can also add psych to your Gemfile to force it.

$ echo "gem 'psych' >> Gemfile" && bundle

Problem solved. Cheers Alessandro!

Write a quick draft while it's fresh

2012-05-15T09:00:00+01:00

As a bootstrapper, it's important that I spend enough time getting my product's name out there. For me, that means blogging. I've recently been writing a couple of paragraphs the instant that I have an idea for a post. That usually means writing "on your mobile" (or in my case, on my iPod).

I used to capture a one line summary of an idea in my todo list, with a view to writing the post up later. By the time I'd get around to it I'd often struggle to recover my thoughts and the inspiration would be long gone.

In the last week I've written several 200 word drafts on my iPod. They've since been edited into blog posts that I'm rather pleased with. If you have an iOS device the iA Writer app (iPhone/iPod/iPad) is great.

In this screenshot of the iPhone version you can see iA Writer's extended keyboard, with extra buttons for common punctuation marks, and cursor keys for navigating left and right in your copy. The iPad version (not shown) also has keys for jumping whole words at the time, which is a significant improvement over the default iPad keyboard.

I seem to write better with iOS than I do with a laptop, presumably because I can't type as fast and that gives me a bit more space to think. Maybe it's that, or maybe it's just because I'm using something a bit different.

Either way, iA Writer on your phone, sync'd with Dropbox is a great way to write the draft. I edit later on the computer, then post it.

Sent from my iPod

Securing Instiki with an SSH tunnel

2012-04-26T00:00:00+00:00

I've been using a wiki a lot recently to keep track of my research. A wiki is the perfect tool for keeping track of all my notes, and the relationships between my ideas.

I've been using Instiki; the UI is clean and is built with familiar technology (it's written in Rails, and its early code was the app from which DHH extracted the Rails framework). As wikis go it takes a fairly low maintenance approach, and lets you concentrate on your content.

Being a Rails app, you can run it with a standard Ruby web server such as Webrick. I started out running it locally on my desktop. When I started working more on my laptop I needed access to the wiki there too, so I moved the app's folder into Dropbox and synchronised the database that way (it uses a local SQLite database). That worked fine until I accidentally started it on both machines at once, and I lost a page of data.

Clearly, I was going to have to host it properly.

There is a fork of Instiki that runs on Heroku. I'm sure it's awesome, but I'm often reluctant to use forks of apps that don't see a lot of use. You've no idea how long the fork will be maintained, and I don't fancy rolling my sleeves up when Heroku deprecate the stack that the port runs on.

So I decided to host it on my VPS. In theory all I'd need to do is to tar up my local instiki folder, copy it over to my server and untar it. After a quick bundle install I should be good to go, and indeed, I was.

I knocked up a quick init script to start/stop the app on bootup/shutdown, and all was well.

Instiki was running unprotected on port 2500. All was not well.

So, what about security?

You really don't want a private wiki listening on an open port. Not only is your data unprotected, but somebody might find a vulnerability in the wiki software and login to your server.

I had planned to filter port 2500 on my firewall, and configure Nginx to act as a proxy on port 80. This wouldn't prevent an attacker from accessing the wiki's home page, but I could secure it in Nginx with HTTP basic auth running over an SSL connection.

How conventional. And what a faff!

Instead, I've firewalled port 2500 on my server and connect to Instiki over an encrypted SSH connection. Better yet, it guarantees that only I can get at it, as only I can connect to my server with ssh!

So now I access Instiki in the browser by connecting to http://localhost:2500.

I've put the ssh command that sets this up in a script, and run it whenever I want access to the wiki. At some point I'll probably run it automatically whenever I start my laptop, but for now I'm happy with running it when I need it.

Here's the script:

$ cat bin/instiki-tunnel
#!/bin/sh

ssh -f my.server.com -L localhost:2500:my.server.com:2500 -N

This is what the ssh options are for:

-f – run in the background just before launching the command.
-L – forwards all connections to localhost on port 2500 to port 2500 on my.server.com, via an encrypted, authenticated SSH tunnel.
-N – prevents an actual command from being run on the server.

You've got to love SSH.