guess-the-sound - project setup

Created with the grunt-init gui template.

---

1. Install grunt and its dependencies

---

This applies whether you are initialising the project, or you've cloned the repo from GitHub (as development dependencies are excluded from the repo by .gitignore):

$ npm install

---

This section obviously only applies if you are initialising the project.

2. Create local repo

---

$ git init
$ git add .
$ git commit -m 'first commit woo!'

3. Create remote repo

---

For clarity, it is recommended that you give the repo the same name as this project (guess-the-sound):

http://github.com/organizations/GuardianInteractive/repositories/new

4. Link the two

---

Assuming you called the remote repo guess-the-sound, you would do

$ git remote add origin https://github.com/GuardianInteractive/guess-the-sound.git
$ git push -u origin master

---

5. Start grunting

---

$ grunt

To watch the styles and data folders for changes:

$ grunt watch

To launch a server - http://local.static.guim.co.uk:9876 (you can change the port in Gruntfile.js):

$ grunt server

It is recommended that you edit your hosts file so that local.static.guim.co.uk redirects to localhost. This avoids cross-domain nonsense, e.g. with fonts. But if you haven't done that you can still access the site at http://localhost:9876).

---

6. Create your app

---

Project anatomy:

• boot
  your boot files, which are responsible for doing any feature detection or picking a code path (if multiple code paths exist, e.g. mobile vs desktop), then loading the interactive. These files have access to <%= projectUrl %> and <%= versionDir %> variables, which are set as appropriate on deployment

• data
  files in here will be bundled together as data.json (see grunt-dir2json for more info)

• gubbins
  for project-specific stuff that shouldn't end up in the finished product, e.g. artwork, shell scripts, Excel files, whatever

• js
  your scripts. The project template currently assumes you are using AMD

• preview
  files to enable previewing the project at different screen sizes etc. (This folder also contains default.html, which is used to render the final index.html)

• files
  any additional files you want to include in the project, besides your index.html, min.css and data.json files (which are auto-generated). E.g. images

• styles
  .scss files, from which min.css is generated

• codeobject.html
  the markup that the user is presented with at launch, whether it is squirted onto a Guardian page, or part of a dedicated index.html file

(The above is correct at the time of writing... if it looks out of date, please correct!)

---

7. Build

---

$ grunt build

You can check that the built version behaves as expected by doing

$ grunt sanitycheck

and visiting http://local.static.guim.co.uk:9876.

8. Deploy

---

You will need to have AWS credentials, either in your environment or in a JSON file somewhere. To add credentials to your environment on OS X, open ~/.bash_profile and add the following lines (with your details, natch):

export AWS_ACCESS_KEY_ID='yourKeyIdHere'
export AWS_SECRET_ACCESS_KEY='yourSecretAccessKeyHere'

Alternatively add the credentials to a JSON file, and specify its path as the credentials option to the deploy task:

{
	"accessKeyId": "yourKeyIdHere",
	"secretAccessKey": "yourSecretAccessKeyHere"
}

It is possible to specify credentials directly within the task config. Do not do this. You may accidentally push your credentials to GitHub.

To deploy, simply do

$ grunt deploy

This will upload the contents of the dist folder to our S3 account (the gdn-cdn bucket). It will then be accessible from http://interactive.guim.co.uk/2013/jul/guess-the-sound/v/1/index.html (the version number will increment with each deploy).