Magic Spells: Deploying an app to AWS OpsWorks
Newcomers to Git often struggle with the unintuitive verbiage and workflows, often referred to as “incantations”. I endured a similarly convoluted process (hence, “Magic Spells”) after setting up 4 applications on AWS OpsWorks for my senior project, Exbedia (more on that here). My goal with this post is to walk you through the mind-bending procedures required to setup a new app on AWS using OpsWorks.
“I don’t know what these commands do, they’re incantations I use every time I make changes to this project.” — Hypothetical novice Git user
GitHub Project Setup
OpsWorks has out of the box support for GitHub repositories, I’ll quickly go through the steps required to get a public repo deployed. I’ll describe the process for a simple Node.js app. OpsWorks expects 2 things from your Node.js app:
- It runs on port 80 or 443
- Has a server.js file used as the entry point
Setting the port number should be straightforward if you know where to look in your code, I wasn’t able to get OpsWorks to detect the PORT environment variable that many packages like Express use. The server.js entry point seems like a strange limitation, but it’s not that bad. The easiest way to handle this is by creating a symlink called server.js. On *nix systems, cd to your project’s directory and run:
ln -s <path_to_your_script> server.js
Check out my hello world Express app on GitHub for an example.
The Magic Spells
Assuming you’ve completed those 2 steps, and pushed your code, let’s get this app deployed! These steps aren’t super detailed, and things can go wrong with AWS at any point in the process — patience is essential here. I spent about 3 hours learning the the spells & their specific order before I finally got it right, hopefully this guide will save you some time.
Here are the 25 magic spells:
- Login to AWS
- Click on OpsWorks
- Click “add stack” and give it a name
- Click layers
- Click add a layer
- Pick a layer type (Node.js), and give it a name
- Add the layer
- Click add instance on the layer you just created
- Click add an instance
- On the new tab, enter a name, and click add
- Click start on the instance you just created
- Wait, up to 10 minutes for the instance to boot and be configured.
- Click apps
- Click add an app
- Give it a name
- Pick a type (Node.js), it has to match the type from #6
- Enter the GitHub URL, ex: https://github.com/shakeelmohamed/express-helloworld.git
- Enter the git branch name of your repo (master, etc.)
- Click add app
- Click deploy
- You may have to wait if your instance hasn’t started yet if you see “No running instances with the OpsWorks status online. You need to start instances before you can deploy your app.”
22. Click deploy
23. Wait for deployment to complete, it shouldn’t take more than a few minutes. Most of mine took under 3 minutes.
24. Click instances
25. Click on the public IP you see, and you should see your web app!
Well, that was unpleasant.
As a casual Heroku user, this process was significantly more painful and I can understand why many developers are using it. Once your initial OpsWork stack is setup, you can literally do a one click “Deploy App”, then AWS will pull the latest bits from GitHub and try to deploy your app.
Very soon I’ll be setting up continuous deployment with a private GitHub repository, and hope to write about that process as well.