Permalink
Browse files

can we call that a first draft?

  • Loading branch information...
1 parent 631645a commit 25a1edc97c0601f7c0c257a3d1a70ade7d3284a8 @lloyd lloyd committed May 20, 2013
Showing with 23 additions and 8 deletions.
  1. +23 −8 nodejs-application-deployment-on-your-terms.md
@@ -20,8 +20,6 @@ In terms of code changes, you must:
2. add `awsbox` as a dependency in your `package.json`
3. ensure your server binds to the port specified in the `PORT` environment variable
-**XXX: Shall I include code here? A diff of the actual delta that this represents?**
-
To provide your amazon credentials, you must set `AWS_ID` and `AWS_SECRET` in your environment, two values which you can attain through the [amazon management console][].
[amazon management console]: http://aws.amazon.com/console/
@@ -52,7 +50,7 @@ The final step to deploy your application is to `git push`:
$ git push MyFirstAWSBOX HEAD:master
-And now your Node.JS application is hosted and running on an EC2 instance. At this point, you've spend about twenty minutes with awsbox. You've made minimal changes to your application to get it deployable. You've deployed a new server and gotten your application up and running in EC2. You've got an easy way to push changes that fits within your existing workflow (you just git push to a remote).
+And now your Node.JS application is hosted and running on an EC2 instance. At this point, you've spend about twenty minutes with awsbox. You've made minimal changes to your application to get it deployable. You've deployed a new server and gotten your application up and running in EC2. Finally, you've got an easy way to push changes that fits within your existing workflow (you just git push to a remote).
Now that you have a feel for how you use awsbox and the basic features it provides, let's take a step back and look at what it actually is and how it works.
@@ -70,7 +68,10 @@ In building awsbox, a main goal was minimal invention, to make it easy to "port"
## awsbox is ... A Machine Image
-During the process of creating an instance, awsbox creates a machine instance from an "Amazon Machine Image", which results in a running server that's ready to accept your node.js application and install it. The ID of the machine image is referenced in the `awsbox` javascript library.
+During the process of creating an instance, awsbox creates a machine instance from an "Amazon Machine Image", which results in a running server that's ready to accept your node.js application and install it. The image is built from the [Amazon Linux AMI][] which is a custom linux distribution provided by amazon, which has access to popular rpm-based package repositories via [yum][]. The ID of awsbox AMI is referenced in the `awsbox` javascript library.
+
+[Amazon Linux AMI]: http://aws.amazon.com/amazon-linux-ami/
+[yum]: http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified
This image is *pre-configured with multiple user accounts*. `ec2-user` is an account that has sudo access to the machine. `proxy` is an account that hosts an [HTTP reverse proxy][] that with a [few steps][] can serve as an SSL server to let you support HTTPS without modifying your application. Finally, the `app` user is the account that hosts all of your application code, your server logs, the server based git repository that you push to, and the [git post-commit hook][] responsible for installing dependencies and starting your server after you push.
@@ -80,14 +81,28 @@ This image is *pre-configured with multiple user accounts*. `ec2-user` is an ac
## awsbox is ... Command Line Tools and Libraries
+At the time you `npm install` awsbox, a collection of javascript libraries and a command line tool are installed locally. The command line tool gives you a much faster way to deploy servers than available through Amazon's web console, and handles most of the complexity of creating an instance in EC2 that is ssh and web accessible.
+The `awsbox` command line tool also provides many command line *verbs* to perform basic administration of your awsbox, which can be listed with `node_modules/.bin/awsbox -h`.
+
+The most interesting verb is `create`, which actually creates a virtual machine.
## awsbox is ... A Pile Of Features and Hooks
+Finally, any non-trivial server requires more than just a Node.JS service. To support the unknown awsbox allows you to [specify yum packages that should be installed][] at instance creation time. For more custom configuration you have two options:
+
+[specify yum packages that should be installed]: https://github.com/mozilla/awsbox/blob/master/doc/JSON.md#packages-optional
+
+**SSH in and install whatever you need to**: The goal of awsbox is to let you move as fast as possible, and sometimes the most expedient way to get a new instance of a service up is to perform them manually and write a README. But a more repeatable solution is available…
+
+**Write scripts to automatically configure software for you**: Awsbox has the [notion of *hooks*][], which occur at various stages of instance creation or deployment. Using these hooks, it's possible to [configure mysql][], [install redis manually][], or do whatever you need to in order to get your service running.
+
+[notion of *hooks*]: https://github.com/mozilla/awsbox/blob/master/doc/JSON.md#remote_hooks-optional
+[configure mysql]: https://github.com/mozilla/browserid/blob/4971e83b897829d866f99c0e398d52a7b3b9ec2b/scripts/awsbox_remote/post_create.sh
+[install redis manually]: https://github.com/mozilla/restmail.net/blob/44306506b1a33ed3c1fbc1b61f13b8d557b80141/aws_scripts/post_create.sh
+
# Is awsbox for Me?
-XXX: Let's reel it back in and keep it real. This is a solution that's
-XXX: Worked fantastic for our team, how else could a handful of folks
-XXX: support 20 distinct alpha/beta services?
+Having a single consistent mechanism of deploying non-critical services has been an incredible efficiency benefit for our team. *Collaboration is easier* when you have a simple and well defined contract between application and environment. *Diagnosis of issues* is faster when you have a consistent set of deployment conventions. Finally, *moving from experiment to production environment is less costly* when an application has all of its dependencies explicitly expressed.
-XXX: the bottom line is...
+If you are looking for a deployment solution for your own experimental Node.JS service, we hope the ideas and design of awsbox are useful to you.

0 comments on commit 25a1edc

Please sign in to comment.