Merge pull request #189 from opdemand/doc-updates

Doc updates post application refactoring

Author: mboersma

README.md

@@ -51,6 +51,10 @@ $ git clone https://github.com/opdemand/deis.git
 $ cd deis
 ```
 
+Cloning the default master branch will provide you with the latest development version
+of Deis.  If you want to deploy the latest stable release, make sure you checkout the
+most recent tag using ``git checkout vX.Y.Z``.
+
 ### 2. Configure the Chef Server
 
 Deis requires a Chef Server. [Sign up for a free Hosted Chef account](https://getchef.opscode.com/signup) if you don’t have one.  You’ll also need a Ruby runtime with RubyGems in order to install the required Ruby dependencies.
@@ -67,11 +71,11 @@ The [Amazon EC2 API Tools](http://aws.amazon.com/developertools/351) will be use
 
 	$ contrib/provision-ec2-controller.sh
 
-Once the `deis-controller` node exists on the Chef server, you *must* log in to the WebUI add deis-controller to the `admins` group.  This is required so the controller can delete the node and client records for any nodes bootstrapped during future `layers:scale` operations.
+Once the `deis-controller` node exists on the Chef server, you *must* log in to the WebUI add deis-controller to the `admins` group.  This is required so the controller can delete node and client records during future scaling operations.
 
 ### 4. Install the Deis Client
 
-Install the Deis client using [Pip](http://www.pip-installer.org/en/latest/installing.html).  Registration will discover SSH keys automatically and use the [standard environment variables](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html#set_aws_credentials_linux) to configure the EC2 provider.
+Install the Deis client using [Pip](http://www.pip-installer.org/en/latest/installing.html) (for latest stable) or by linking `<repo>/client/deis.py` to `/usr/local/bin/deis` (for dev version).  Registration will discover SSH keys automatically and use the [standard environment variables](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SettingUp_CommandLine.html#set_aws_credentials_linux) to configure the EC2 provider.
 
 ```bash
 $ sudo pip install deis
@@ -94,29 +98,41 @@ Uploading EC2 credentials... done
 
 ### 5. Create & Scale a Formation
 
-Find an application you’d like to deploy, or clone [an example app](https://github.com/opdemand/example-nodejs-express).  Change into the application directory and use `deis create` to initialize a new formation in a specific EC2 region. Use the `deis layers:scale` command to provision nodes that will be dedicated to this formation.
+Use the Deis client to create a new formation named "dev" that
+has a default layer that serves as both runtime (hosts containers)
+and proxy (routes traffic to containers).  Scale the default layer
+up to two nodes.
 
 ```bash
-$ cd <my-application-repo>
-$ deis create --flavor=ec2-us-west-2
-Creating formation... done, created peachy-waxworks
-Git remote deis added
+$ deis formations:create dev --flavor=ec2-us-west-2
+Creating formation... done, created dev
 
-Creating runtime layer... done
-Creating proxy layer... done
+Creating runtime layer... done in 1s
 
-Use deis layers:scale proxy=1 runtime=1 to scale a basic formation
+Use `deis nodes:scale dev runtime=1` to scale a basic formation
 
-$ deis layers:scale proxy=1 runtime=1
-Scaling layers... but first, coffee!
-...done in 232s
+$ deis nodes:scale dev runtime=2
+Scaling nodes... but first, coffee!
+...done in 251s
 
-Use `git push deis master` to deploy to your formation
+Use `deis create --formation=dev` to create an application
 ```
 
-### 6. Deploy your Application
+### 6. Deploy & Scale an Application
+
+Change into your application directory and use  ``deis create --formation=dev`` 
+to create a new application attached to the dev formation.
+
+To deploy the application, use `git push deis master`.  
+Deis will automatically deploy Docker containers 
+and configure Nginx proxies to route requests to your application.
 
-Use `git push deis master` to deploy your application.  Deis will automatically deploy Docker containers and configure Nginx proxies to route requests to your application.  To learn more, use `deis help` or browse [the documentation](http://docs.deis.io).
+Once your application is deployed, you use ``deis scale web=4`` to 
+scale up web containers.  You can also use ``deis logs`` to view 
+aggregated application logs, or ``deis run`` to run one-off admin
+commands inside your application.
+
+To learn more, use `deis help` or browse [the documentation](http://docs.deis.io).
 
 ```bash
 $ git push deis master
@@ -142,6 +158,18 @@ Total 146 (delta 84), reused 47 (delta 22)
 
 $ curl -s http://ec2-198.51.100.36.us-west-2.compute.amazonaws.com
 Powered by Deis!
+
+$ deis scale web=4
+Scaling containers... but first, coffee!
+done in 12s
+
+=== peachy-waxworks Containers
+ 
+--- web: `node server.js`
+web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-2)
+web.2 up 2013-09-23T19:36:48.741Z (dev-runtime-1)
+web.3 up 2013-09-23T19:36:48.758Z (dev-runtime-1)
+web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-2)    
 ```
 
 ## Credits

api/fields.py

@@ -7,8 +7,6 @@
 
 from django import forms
 from django.db import models
-from json_field import JSONField
-from yamlfield.fields import YAMLField
 
 
 class UuidField(models.CharField):
@@ -53,60 +51,6 @@ def formfield(self, **kwargs):
         return super(UuidField, self).formfield(**kwargs)
 
 
-class EnvVarsField(JSONField):
-
-    """
-    A text field that accepts a JSON object, coercing its keys to uppercase.
-    """
-    pass
-
-
-class DataBagField(JSONField):
-    """
-    A text field that accepts a JSON object, used for storing Chef data bags.
-    """
-    pass
-
-
-class ProcfileField(JSONField):
-    """
-    A text field that accepts a JSON object, used for Procfile data.
-    """
-    pass
-
-
-class CredentialsField(JSONField):
-    """
-    A text field that accepts a JSON object, used for storing provider
-    API Credentials.
-    """
-    pass
-
-
-class ParamsField(JSONField):
-    """
-    A text field that accepts a JSON object, used for storing provider
-    API Parameters.
-    """
-    pass
-
-
-class CloudInitField(YAMLField):
-    """
-    A text field that accepts a YAML object, used for storing cloud-init
-    boostrapping scripts.
-    """
-    pass
-
-
-class NodeStatusField(JSONField):
-    """
-    A text field that accepts a YAML object, used for storing cloud-init
-    boostrapping scripts.
-    """
-    pass
-
-
 try:
     from south.modelsinspector import add_introspection_rules
     # Tell the South schema migration tool to handle our custom fields.

api/models.py

@@ -19,6 +19,7 @@
 from django.dispatch import receiver
 from django.dispatch.dispatcher import Signal
 from django.utils.encoding import python_2_unicode_compatible
+from json_field.fields import JSONField  # @UnusedImport
 
 from api import fields, tasks
 from provider import import_provider_module
@@ -111,7 +112,7 @@ class Provider(UuidAuditedModel):
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
     id = models.SlugField(max_length=64)
     type = models.SlugField(max_length=16, choices=PROVIDERS)
-    creds = fields.CredentialsField(blank=True)
+    creds = JSONField(blank=True)
 
     class Meta:
         unique_together = (('owner', 'id'),)
@@ -148,7 +149,7 @@ class Flavor(UuidAuditedModel):
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
     id = models.SlugField(max_length=64)
     provider = models.ForeignKey('Provider')
-    params = fields.ParamsField(blank=True)
+    params = JSONField(blank=True)
 
     class Meta:
         unique_together = (('owner', 'id'),)
@@ -167,7 +168,7 @@ class Formation(UuidAuditedModel):
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
     id = models.SlugField(max_length=64, unique=True)
     domain = models.CharField(max_length=128, blank=True, null=True)
-    nodes = fields.JSONField(default='{}', blank=True)
+    nodes = JSONField(default='{}', blank=True)
 
     class Meta:
         unique_together = (('owner', 'id'),)
@@ -256,7 +257,7 @@ class Layer(UuidAuditedModel):
     ssh_port = models.SmallIntegerField(default=22)
 
     # example: {'run_list': [deis::runtime'], 'environment': 'dev'}
-    config = fields.JSONField(default='{}', blank=True)
+    config = JSONField(default='{}', blank=True)
 
     class Meta:
         unique_together = (('formation', 'id'),)
@@ -390,7 +391,7 @@ class Node(UuidAuditedModel):
 
     provider_id = models.SlugField(max_length=64, blank=True, null=True)
     fqdn = models.CharField(max_length=256, blank=True, null=True)
-    status = fields.NodeStatusField(blank=True, null=True)
+    status = JSONField(blank=True, null=True)
 
     class Meta:
         unique_together = (('formation', 'id'),)
@@ -438,7 +439,7 @@ class App(UuidAuditedModel):
     id = models.SlugField(max_length=64, unique=True)
     formation = models.ForeignKey('Formation')
 
-    containers = fields.JSONField(default='{}', blank=True)
+    containers = JSONField(default='{}', blank=True)
 
     def __str__(self):
         return self.id
@@ -666,7 +667,7 @@ class Config(UuidAuditedModel):
     app = models.ForeignKey('App')
     version = models.PositiveIntegerField()
 
-    values = fields.EnvVarsField(default='{}', blank=True)
+    values = JSONField(default='{}', blank=True)
 
     class Meta:
         get_latest_by = 'created'
@@ -690,9 +691,9 @@ class Build(UuidAuditedModel):
 
     image = models.CharField(max_length=256, default='deis/buildstep')
 
-    procfile = fields.ProcfileField(blank=True)
+    procfile = JSONField(blank=True)
     dockerfile = models.TextField(blank=True)
-    config = fields.EnvVarsField(blank=True)
+    config = JSONField(blank=True)
 
     url = models.URLField('URL')
     size = models.IntegerField(blank=True, null=True)