mozilla / awsbox

INACTIVE - http://mzl.la/ghe-archive - A featherweight PaaS on top of Amazon EC2 for deploying node apps

A Lightweight DIY PaaS for Amazon Web Services

Amazon Web Services (AWS) "Elastic Compute Cloud" provides low cost, instant on VMs that can be used to deploy any kind of service. AWS also provides a full set of APIs that make it possible to programatically allocate servers. Finally, AWS offers the ability to create "template" instances (Amazon Machine Images) that are VM snapshots.

The problem: For small scale nodejs projects, there's a lot of administrative boiler plate work that one must to set up a machine. You must install web server software, set up security policies and network access, copy up your keypair, determine how you'll deploy your software on the new VM, etc.

"Platform as a service" providers like heroku make most of these decisions for you, providing a demand spun "vm-like" thing that you can deploy code on by adhering to a couple conventions and git pushing. Where heroku breaks down is in generativity - you are limited to doing things that heroku has thought of, and when you want to do something custom (install a new native software library, run an experimental database for which you cannot find a third party hosted provider) - you are screwed.

Also, heroku is relatively expensive. The moment you want to run two processes, you're paying 0.05$/hr for that process vs. on aws where you can purchase a "micro" instance for 0.02$/hr for the whole VM. The final area of expense is in "add-ons" - service providers that offer things like hosted databases, email sending, etc. A small scale database can cost another .015$/hr.

But Wait! What about nodejitsu? Well, probably use them: they're awesome, smart, admirably share their work, have a free service for non-commercial deployments, and just work for most apps. But sometimes you might want full control. That you? Read on... (NOTE: awsbox is built on lots of nodejistu stuffs).

So what we maybe want is the convenience of Nodejitsu and Heroku, and the pricing and freedom of a raw amazon image...

The solution: awsbox is a set of nodejs scripts, a command line utility, and a template image (AMI). Together it allows you to deploy a new server from the command line that is pre-configured to run your Node.JS service.

Features

• nodejs focused - While other stacks could be supported in the future, awsbox is laser focused on node.js to start.
• full root access - awsbox just gets you started, after that you can do Whatever You Want.
• magic ssh key config - Your SSH key will be copied up and installed for you.
• git push support - After you provision a vm, it's pre-configured so you can push to deploy
• multi-region support - awsbox base AMIs are published in every region AWS supports, so you can deploy anywhere.
• command line or programmatic usage - type at it, or script it.
• OS level user isolation - all deployed code is run with user permissions under a single account.
• HTTP forwarding with custom 503 page - nginx is pre-configured to forward requests to your nodejs process bound to a local port.
• SSL support - By default your process runs with a self-signed cert. Enabling SSL support is as easy as copying up a private key and certificate in PEM format.
• WebSocket support - AWSBOX fully supports WebSockets, via socket.io or otherwise.
• Route53 support - manage your DNS from the command line, and have DNS set up for your boxes at creation time.

Get Started

Start by working through the tutorial. Then have a look at the Hello World sample app. And after that, check out the documentation in this repository.

awsbox's Issues

make it clearer that ~app/code/ is completely ephemeral

Use child_process.spawn instead of child_process.exec in ssh commands

Long script commands can easily exceed the exec() buffer size. I think the streaming approach would fit better here.

Add user data to the awsbox command line

For security reasons, it would be useful to have the option to pass user data (http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AESDG-chapter-instancedata.html) to the "create" sub-command. If this is of interest to anyone, I'll try to fit in a pull request for it.

node isn't in app user's path

forever is in app's path, node isn't.

Workaround: /usr/local/bin/node ~/node_modules/.bin/forever list

port to awssum

Currently the project uses aws-lib, which is fine. But awssum is better in terms of api coverage and simplicity. I experimented with a port and the amount of work is low, and the net change is rather small.

/cc @chilts @6a68

Node 0.10 (or configurable versions?)

Node 0.10 is out and some libraries are starting to depend on it.

Would it be possible to install nvm (Node Version Manager) on the ami and configure which version of node will run during instance creation?

log rotation

Log files grow without limit. How about rotating them daily and by default removing logs over seven days old?

For example, for a process foo specified in the .awsbox.json file, the setup scripts could create /etc/logrotate.d/foo with the following contents:

/home/app/var/log/foo.log {
    missingok
    notifempty
    copytruncate
    rotate 7
}

I don't know what the best way to make all these crazy parameters available through the config is. Perhaps the addition of the argument --log-rotate-days would be enough?

de-brand 503 page

the 503 page mentions browserid. It should talk about awsbox instead and provide basic instructions for how to deploy via git.

specify VM size on command line

with something like

awsbox create -t t1.micro foo

Should be able to list available sizes with:

awsbox create -h

app doesn't startup after server reboot

After rebooting the server instance in the EC2 Management Console the app doesn't startup. the http-proxy seems to be running as I get the default 500 page.

the app log file says: "warn: Forever detected script exited with code: null"

Websocket support

I'd love to see this support a proxy that is http 1.1 compatible (HAProxy, node-http-proxy) - the use of nginx prohibits this from being able to use web sockets, which is a bummer.

tutorial style documentation

is needed

Work with deb based distros [Ubuntu/Debian etc]?

For various external reasons, I use the official ubuntu AMIs on AWS. It would be totally awsome if awsbox was natively able to use them (including juju/upstart/APT integration)

upgrade to node 0.8.12

cause it's time

No file found for route css/application.css

I have a problem on here using the current awsbox setup with connect-assets it doesn't seem to find my css or even start my app in production.

Updated cairo installation in template AMI

Would it be possible to update your template AMI's cairo installation according to https://github.com/LearnBoost/node-canvas/wiki/Installation---Amazon-Linux-AMI-%28EC2%29 ? I'd love to use awsbox "out of the box" for an app using this library and currently, this fails.

Initial yum run during vm creation fails

The initial vm creation runs yum to install updates. It correctly resolves dependencies, but then fails when downloading packages with errors like:

http://packages.us-east-1.amazonaws.com/2012.03/updates/d7a89e5442bd/x86_64/Packages/aws-apitools-ec2-1.6.0.0-1.0.amzn1.noarch.rpm: [Errno -1] Package does not match intended download. Suggestion: run yum --enablerepo=amzn-updates clean metadata
Trying other mirror.

Not sure what it means--the packages are failing a checksum it expects from cached metadata?

Not sure what the correct behavior for awsbox is when this happens. Running the clean metadata command might fix this particular problem, but yum could fail for a number of reasons outside of awsbox's control.

The one thing I would change for sure: it would be nice to know if awsbox aborted any further commands needed to set up the vm. My terminal just has a bunch of errors from yum and that's it--I don't know what (if anything) got skipped.

npm install on the VM should only install production resources

like, npm install --production

?

deployment of scripts in subdirs doesn't work

if you've got a nodejs script under server/bin/bigtent, the push fails because path to logfile relies on subdirectories that don't exist.

Allow different regions

I had a quick look into the code and it shouldn't be too difficult. I guess the main problem would be maintaining AMI's cross region. That may be a nightmare...

Enable gzip in the reverse proxy

http://www.webpagetest.org/result/121010_P6_8HF/1/performance_optimization/#compress_text

(originally filed at mozilla/123done#43)

awsbox create fails if you don't have an RSA ssh key

I only had a DSA key, and "awsbox create" doesn't use it. It should support DSA keys, or if there is a good reason to only support RSA, then the tutorial should tell you to make one.

document in HOW_DO_I how to have custom configuration files

awsbox git doens't always remove remote

On several occasions I did a destroy and create with the same name.

Sometimes awsbox removes the remote and other times it didn't. If it didn't, then git has the old IP address in .git/config.

I see code in awsbox.js and lib/git.js for cleaning up remotes, so not too sure. I didn't see any errors after the destroy command.

STR

1. ./node_modules/.bin/awsbox create -n devbigtent
2. ./node_modules/.bin/awsbox destroy devbigtent

Expected

git remote should only show my normal remotes

Actual

git remote has awsbox generated IP address.

This doesn't repro 100% of the time... try several times, maybe doing a git push to the box, etc.

lloyd.pub

Why is there lloyd's public ssh key in my ec2-user directory? I'm a little bit concerned with this.

proxy user is not putting logs in var/log but in .forever

this is not discoverable nor symmetric with how the app user works.

An option to specify additional ports to open in AWS security group

It would be useful to have an option to specify ports to open in addition to the defaults in awsbox. E.g., smtp.

Support https out of the box

It would be great if awsbox generated a self-signed certificate and made your node app available over https.

After initial creation, a user can easily overwrite the certs with a real SSL cert and aws won't step on it during later deployments.

Multiple apps/domains per VM

Is this currently possible? Can't see anything in the docs. If not then I guess this is a feature request...

Can you change the instance size of the server?

Wondering if that is in configs?

After creation with `--ssl disable`, proxy server requires restart to disable ssl

SSL seems to be enabled even though the box was created with --ssl disable, and needs a manual restart for it to kick in.

allow specification of public URL during initial VM creation

something like

awsbox create -u http://123done.org 123done

this url should then be available to deployment in environment

awsbox sometimes doesn't tear down DNS

Had some trouble tearing down the translate environment this afternoon, @lloyd suspected it was an awsbox DNS bug:

jareds-partybus-2:mozilla-browserid jhirsch$ ./scripts/deploy.js destroy translate
awsbox cmd: node_modules/.bin/awsbox destroy translate
trying to destroy VM for translate: failed: no such vm

Meanwhile, I saw the entry in the list of active awsbox nodes:

jareds-partybus-2:mozilla-browserid jhirsch$ ./scripts/deploy.js list
awsbox cmd: node_modules/.bin/awsbox list

... 

  translate {i-60be6301}:   
    23.20.197.43, c1.medium, launched 6 days ago

...

So I used the ID, which unset the DNS, curiously enough:

jareds-partybus-2:mozilla-browserid jhirsch$ ./scripts/deploy.js destroy i-60be6301
awsbox cmd: node_modules/.bin/awsbox destroy i-60be6301
trying to destroy VM for i-60be6301: done
trying to remove git remote: failed: no such remote
trying to remove DNS: translate.personatest.org
deleting translate.personatest.org: done

script the creation of the awsbox base AMI

IIUC, the base awsbox AMI is currently a binary blob, built by hand. It would be great if the details of re-creating this image could be reified in the code, both to document what exactly is on there and to enable re-creating the image if it's accidentally lost.

Some puppet or chef recipes would be ideal, but even just a bash script that does all the configuration would be very useful.

vim!

because people do.

serve /ver.txt magically

we should configure nginx by default to serve /ver.txt so as a user of awsbox you get this feature for free.

set `hostname` to the public facing DNS name of the host

Perhaps this will cause issues I haven't thought through, but current when I ssh into an awsbox hostname is something like 'domU-12-30-37-0E-C5-52'.

It would be more useful if awsbox did hostname myname.personatest.org, so when I'm looking through multiple terminal windows I can see which one is which.

pushing code that has deps specified by git url fails

This is because the ENV in which we run npm install has a GIT_DIR var in it which breaks things.

Error: EISDIR, illegal operation on a directory for --keydir

STR

1. clone mozilla private repo with ssh keys
2. clone 123done.org
3. npm install
4. ./node_modules/.bin/awsbox create -u http://native-persona.123done.org --ssl disable -n native-persona -t m1.small --keydir ~/identity-pubkeys/

Expected:
Magick

Actual:
At the end of the deploy... boom:

   ... reading public keys from /home/ozten/identity-pubkeys/

fs.js:381
  var r = binding.read(fd, buffer, offset, length, position);
                  ^
Error: EISDIR, illegal operation on a directory
    at Object.fs.readSync (fs.js:381:19)
    at Object.fs.readFileSync (fs.js:208:28)
    at /home/ozten/123done/node_modules/awsbox/lib/key.js:64:24
    at Array.forEach (native)
    at exports.addKeysFromDirectory (/home/ozten/123done/node_modules/awsbox/lib/key.js:61:11)
    at Object.oncomplete (fs.js:297:15)

Consider supporting npm install -g awsbox

Rather than calling the executable from node_modules, allow a global installation of the executable?

noname deployment when trying to create named deployment

http://pastebin.mozilla.org/1648943

Actual:
noname in .git/config

Expected:
temporary_oauth_bigtent

generalize DNS support, move to route53

currently there are some features to automatically set up DNS. it would be useful to move them off of zerigo and onto route53 - given that users of awsbox already have an amazon account.

Discoverability of existing deployments

Not sure what I'm asking for exactly....

Use case: I need to update 10.0.4.21 and that is running codebase X.

I stumble around in the X repo trying to remember which steps to do.

I inevitably read my .git/config to figure out 10.0.4.21 and then remember to git push env-X master:master.

The text shown on first deploy is super helpful. I guess I want that printed again, as well as a list of active deployments for this repo.

./node_modules/.bin/awsbox list shows me {} right now, filed Issue #18.

I'll try to come up with an actual feature request ;) but maybe ./node_modules/.bin/awsbox list and ./node_modules/.bin/awsbox help where help is repo specific.

Git submodules are not initialized by awsbox

I could be going completely insane, but I don't think submodules are being initialized by awsbox.

create --help should not attempt deploy a VM named --help

Steps to Reproduce

1. ./node_modules/.bin/awsbox create --help

Actual

A nameless VM is launched

Expected

Help specific to the create command or an error message

Document the -g option

-g option has been added to awsbox per
#49

But I do not see it here:
awsbox create -help

We need to document it's use here...
;-)

list command has empty output

I haven't touched a deployment in several weeks.

I do

ozten@nutria:~/bigtent$ git push temporary_bigtent master:master
... lots of output, looks good
ozten@nutria:~/bigtent$  ./node_modules/.bin/awsbox list
{}

Hitting 23.20.195.22 I see the app.

tar: This does not look like a tar archive

sean@ubuntu:~/Projects/eyedee.me (awsbox) $ git push eyedeeme awsbox
Counting objects: 288, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (136/136), done.
Writing objects: 100% (288/288), 71.00 KiB, done.
Total 288 (delta 130), reused 283 (delta 128)
remote: >> staging code to /tmp/deploy11273-1310-ch4jx3
remote: >> exporting current code
remote: fatal: Not a valid object name
remote: tar: This does not look like a tar archive
remote: tar: Exiting with failure status due to previous errors
remote: ERROR: while exporting current code:
remote: 
remote: Error: Command failed: fatal: Not a valid object name
remote: tar: This does not look like a tar archive
remote: tar: Exiting with failure status due to previous errors
remote: 
To [email protected]:git
 * [new branch]      awsbox -> awsbox

Include the browserid repo in the AMI?

That's probably not a good idea because it means awsbox would be Persona-specific, but the initial push takes a really long time and it would be nice if it could be made smaller.

If the AMI had some snapshot of the browserid repo already loaded, it would mean that the first push wouldn't have so many commits to push.

(This is a half-baked idea, but I figured I'd write it down while I'm waiting for my push to finish...)

incremental output during deployment

when you git push, the post-update.js hook currently buffers output of subprocesses and dumps all at once. This sucks. We should incrementally display output on the terminal.