Update 2013-04-14: MongoHQ now has better documentation on S3/IAM security configuration.

I spent a few hours yesterday convincing MongoHQ to back up a Mongo database to an Amazon S3 bucket via an Amazon “IAM” account. Here’s the secret recipe. Hopefully it saves someone time.

Context: MongoHQ, which I’m using with one of my work projects right now, is a service that hosts MongoDB databases. It integrates with Heroku, allowing you to get started on a Heroku app using MongoDB very quickly. MongoHQ supports hourly and daily backup of their databases to Amazon S3 buckets, but alas, not yet for databases provisioned automatically via Heroku. So if you want to step up to a backed-up database you’ll have to set up your own. Here are the steps I followed to do it.

Secret decoder ring:
S3 = Amazon Web Services Management Console, S3 tab.
IAM = Amazon Web Services Management Console, IAM tab.
MHQ = Mongo HQ console.
HKU = Heroku.

Recipe:

1. S3 : Create a bucket for your app’s backups, e.g. “my-app-backups”.
2. IAM: Create an IAM User account for MongoHQ to use, e.g. “mongohq”. Download the credentials and store them safely.
3. IAM: Create an IAM Group to contain all users with backup permission, e.g. “myapp-backup-writers”.
4. IAM: Add the mongohq User account to the newly created Group.
5. IAM: Using the Permissions tab of the Group’s properties attach a new security policy, granting permission to write to the myapp-backups bucket. See below for a sample policy.
6. MHQ: Sign up for your own MongoHQ account.
7. MHQ: Create the database you wish to use with Heroku.
8. MHQ: Select the “Backups” tab and enter the IAM User credentials from step 2.
9. MHQ: Click “Save Settings”. If all is well you’ll see a message, “Setting Updated”.*
10. MHQ: Create a new user on the Database Users tab.
11. MHQ: Copy down the Mongo URI string from the Database Info tab, substituting your user name and password from step 10.
12. HKU: In the root directory of your Heroku app do “heroku config:add MONGOHQ_URL=’URI’”. URI is the Mongo URI from step 11. (Normally Heroku sets this variable for you when it provisions a MongoHQ database. You’re overriding it with a link to your own database.)

* Step 9 is where I got stuck. It worked fine with my own personal security credentials, but not with the IAM account I created specifically for MongoHQ to use. (I wanted more security… giving your main account credentials to a 3rd party site isn’t smart.) I fiddled around with the security policy for quite a while, and eventually discovered I needed the “ListAllMyBuckets” permission. Here’s the security policy that worked for me:

    {
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [ "s3:ListAllMyBuckets" ],
          "Resource": "arn:aws:s3:::*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:PutObjectAcl"
          ],
          "Resource": [
            "arn:aws:s3:::MY-APP-BACKUPS/*"
          ]
        }
      ]
    }