Merge pull request #613 from opdemand/localdev-docs

Update Local Development Documentation

Author: mboersma

docs/components/controller.rst

@@ -29,7 +29,7 @@ The controller stack includes:
 * PostgreSQL database as a backing store for Django
 * Celery / RabbitMQ for dispatching tasks
 * A lightweight *gitreceive* hook for ``git push`` access control
-* Docker and Buildstep to process Heroku Buildpacks
+* Docker and Slugbuilder to process Heroku Buildpacks and Dockerfiles
 
 Follow the :ref:`Operations Guide <operations>` to setup your own private
 Deis controller.

docs/contributing/localdev.rst

@@ -5,40 +5,44 @@
 
 Local Development
 =================
-We have tried to make it simple to hack on Deis, but as an open PaaS 
-there are necessarily several moving pieces and some setup required. 
-We welcome any suggestions for automating or simplifying this process.
+
+We have tried to make it simple to hack on Deis, but as an open PaaS, there are
+necessarily several moving pieces and some setup required. We welcome any suggestions for
+automating or simplifying this process.
 
 Prerequisites
 -------------
-We strongly recommend using `Vagrant`_ with `VirtualBox`_ so you can 
-develop inside a set of isolated virtual machines. You will need:
+
+We strongly recommend using `Vagrant`_ with `VirtualBox`_ so you can develop inside a set
+of isolated virtual machines. You will need:
 
  * Vagrant 1.3.5+
  * VirtualBox 4.2+
 
 Fork the Repository
 -------------------
-To get Deis running locally, first `fork the Deis repository`_ at GitHub.com.
-Then clone your fork of the repository for local development:
+
+To get Deis running locally, first `fork the Deis repository`_, then clone your fork of
+the repository for local development:
 
 .. code-block:: console
 
-	$ git clone https://github.com/<username>/deis.git
+	$ git clone git@github.com:<username>/deis.git
 	$ cd deis
 	$ export DEIS_DIR=`pwd`  # to use in future commands
 
 Configure a Chef Server
 -----------------------
-Deis relies on Chef Server to provide a battle-tested foundation for
-hosting `cookbooks`_ used to configure :ref:`Nodes <node>` and
-`data bags`_ used to store cluster configuration.
-You can run a local Chef Server or use a Hosted Chef Server.
+
+Deis relies on a Chef Server to provide a battle-tested foundation for hosting
+`cookbooks`_ used to configure :ref:`Nodes <node>` and `data bags`_ used to store cluster
+configuration. You can host your own Chef Server or use a Hosted Chef Server.
 
 Local Chef Server
 `````````````````
-For development purposes, you can spin up a local Chef Server using Vagrant.
-Please note it will take up at least 1GB of RAM.  From your workstation:
+
+For development purposes, you can spin up a local Chef Server using Vagrant. Please note
+that it will take up at least 1GB of RAM. From your workstation:
 
 .. code-block:: console
 
@@ -61,8 +65,8 @@ Now use ``knife client list`` to test connectivity to the local Chef Server:
 Self-hosted Chef Server
 ```````````````````````
 
-Alternatively, you can `host your own Chef server`_ on your own hardware.
-From your server:
+Alternatively, you can `host your own Chef server`_ on your own hardware. From your
+server:
 
  * visit `the Chef install page`_ in your web browser
  * Click on the "Chef Server" tab and then select the menus that match your operating system
@@ -73,12 +77,15 @@ From your server:
  * configure your admin key and validator
  * configure the knife command with :code:`knife configure --initial`
 
-You should now have a Chef server and a separate workstation to create your configurations.
+You should now have a Chef server and a separate workstation to create your
+client configuration.
 
 Hosted Chef Server
 ``````````````````
+
 If you don't want to run your own Chef server, you can
-`sign up for a free Hosted Chef account`_.
+`sign up for a free Hosted Chef account`_. This is a free service for up to 5 nodes. After
+that, you'll have to start paying.
 
  * `Login to the Chef Server <https://preview.opscode.com/login>`_
  * Click on the ``Administration`` tab and choose your organization
@@ -92,11 +99,12 @@ Now use ``knife client list`` to test connectivity to the local Chef Server:
     $ knife client list
     gabrtv-validator
 
-You should see at least the validator key for your Chef organization.
-If not, your `knife.rb`_ configuration or Chef keys are probably incorrect.
+You should see at least the validator key for your Chef organization. If not, your
+`knife.rb`_ configuration or Chef keys are probably incorrect.
 
 Upload Cookbooks
 ----------------
+
 Upload the current Deis cookbooks using Berkshelf:
 
 .. code-block:: console
@@ -106,23 +114,35 @@ Upload the current Deis cookbooks using Berkshelf:
     $ berks install        # install cookbooks to your local berkshelf
     $ berks upload         # upload berkshelf cookbooks to the chef server
 
+SSH Access
+----------
+
+The Controller needs to be able to run Vagrant commands on your host machine.  It does
+this via SSH. Therefore you will need a running SSH server open on port 22 and a means to
+broadcast your hostname to local DNS.
+
+ * On Mac OSX you just need to go to "System Preferences > Sharing" and enable "Remote Login"
+ * On Debian-flavoured Linux you just need to ``sudo apt-get install openssh-server avahi-daemon``
+
 Provision the Controller
 ------------------------
-Now that the Chef Server is in place with the latest version of our cookbooks,
-we can provision the :ref:`controller`.
+
+Now that the Chef Server is in place with the latest version of our cookbooks, we can
+provision the :ref:`controller`.
 
 .. code-block:: console
 
     $ cd $DEIS_DIR/contrib/vagrant
-    $ ./provision-controller.sh
+    $ ./provision-vagrant-controller.sh
 
-The provisioning process will ask a few questions and then run a
-``knife bootstrap`` of the controller.
+The provisioning process will ask a few questions and then run a ``knife bootstrap`` of
+the controller.
 
 Add Controller to Admin Group
 `````````````````````````````
-In order for the controller to delete records on the Chef Server,
-it must be part of the Admin group.
+
+In order for the controller to delete records on the Chef Server, it must be part of the
+Admin group.
 
 For a Local Chef Server
 
@@ -138,19 +158,12 @@ For a Hosted Chef Server
  * Under "Clients" heading, toggle the "deis-controller" radio button
  * Save changes
 
-SSH Access
-``````````
-The Controller needs to be able to run Vagrant commands on your host machine. 
-It does this via SSH. Therefore you will need a running SSH server open on port 22
-and a means to broadcast your hostname to local DNS.
-
- * On Mac OSX you just need to go to "System Preferences > Sharing" and enable "Remote Login"
- * On Debian-flavoured Linux you just need to ``sudo apt-get install openssh-server avahi-daemon``
-
 Install the Client
 ------------------
-In a development environment you'll want to use the latest version of the client.
-Install its dependencies by using the Makefile and symlinking ``client/deis.py`` to ``deis`` on your local workstation.
+
+In a development environment you'll want to use the latest version of the client. Install
+its dependencies by using the Makefile and symlinking ``client/deis.py`` to ``deis`` on
+your local workstation.
 
 .. code-block:: console
 
@@ -162,8 +175,9 @@ Install its dependencies by using the Makefile and symlinking ``client/deis.py``
 
 Register an Admin User
 ----------------------
-Use the Deis client to register a new user on the controller.
-As the first user, you will receive full admin permissions.
+
+Use the Deis client to register a new user on the controller. As the first user, you will
+receive full admin permissions.
 
 .. code-block:: console
 
@@ -175,6 +189,15 @@ As the first user, you will receive full admin permissions.
     Registered myuser
     Logged in as myuser
 
+.. note::
+
+    As of v0.5.1, the proxy was removed for Deis platform services. It has yet to be added
+    back in. See `issue 535`_ for more details.
+
+    As a workaround, use the following:
+
+    :code:`deis register http://deis-controller.local:8000`
+
 Once the user is registered, activate the Vagrant provider with:
 
 .. code-block:: console
@@ -198,40 +221,45 @@ Add your SSH key for ``git push`` access using:
 
 Deploy a Vagrant Formation
 --------------------------
-These are 3 default flavors of Vagrant nodes: 512MB, 1024MB and 2048MB.
-To create a formation with a 512MB nodes:
+
+These are 3 default flavors of Vagrant nodes: 512MB, 1024MB and 2048MB. To create a
+formation with a 512MB nodes:
 
 .. code-block:: console
 
     $ deis formations:create dev --flavor=vagrant-512
     $ deis nodes:scale dev runtime=1
 
-This will use the Deis :ref:`Provider` API to spin up a new Vagrant node as
-part of a single-host formation.  The scaling process can take ~ 5 min
-as Vagrant boots a host and runs through the first Chef converge.
+This will use the Deis :ref:`Provider` API to spin up a new Vagrant node as part of a
+single-host formation. The scaling process can take ~ 5 min as Vagrant boots a host and
+runs through the first Chef converge.
 
-Once ``nodes:scale`` returns, your local development environment is running!
-Follow the rest of the :ref:`Developer Guide <developer>` to 
-deploy your first application.
+Once ``nodes:scale`` returns, your local development environment is running! Follow the
+rest of the :ref:`Developer Guide <developer>` to deploy your first application.
 
 Useful Commands
 ---------------
+
 Once your controller is running, here are some helpful commands.
 
 Tail Logs
 `````````
+
 .. code-block:: console
 
-    $ vagrant ssh -c 'sudo tail -f /var/log/upstart/deis-* /var/log/deis/*'
+    $ vagrant ssh -c 'sudo docker logs --follow=true deis-server'
+    $ vagrant ssh -c 'sudo docker logs --follow=true deis-worker'
 
 Restart Services
 ````````````````
+
 .. code-block:: console
 
     $ vagrant ssh -c 'sudo restart deis-worker && sudo restart deis-server'
 
 Django Admin
 ````````````
+
 .. code-block:: console
 
     $ vagrant ssh              # SSH into the controller
@@ -244,6 +272,7 @@ Have commands other Deis developers might find useful? Send us a PR!
 
 Standards & Test Coverage
 -------------------------
+
 When changing Python code in the Deis project, keep in mind our :ref:`standards`.
 Specifically, when you change local code, you must run
 ``make flake8 && make coverage``, then check the HTML report to see
@@ -272,6 +301,7 @@ that test coverage has improved as a result of your changes and new unit tests.
 
 Pull Requests
 -------------
+
 Please create a GitHub `pull request`_ for any code changes that will benefit Deis users
 in general. This workflow helps changesets map well to discrete features.
 
@@ -280,6 +310,7 @@ ensure the pull request doesn't break any tests or reduce code coverage.
 
 Cookbook Development
 --------------------
+
 If you want to modify Deis' Chef recipes, you should also clone the `deis-cookbook`_
 repository:
 
@@ -300,3 +331,4 @@ Please see `deis-cookbook`_ for information about contributing Chef code to Deis
 .. _`fork the Deis repository`: https://github.com/opdemand/deis/fork
 .. _`deis-cookbook`: https://github.com/opdemand/deis-cookbook
 .. _`pull request`: https://github.com/opdemand/deis/pulls
+.. _`issue 535`: https://github.com/opdemand/deis/issues/535

docs/gettingstarted/concepts.rst

@@ -98,5 +98,4 @@ See Also
 .. _`Twelve Factor model`: http://12factor.net/build-release-run
 .. _`backing services`: http://12factor.net/backing-services
 .. _`environment variables`: http://12factor.net/config
-.. _`Buildstep`: https://github.com/opdemand/buildstep
 .. _`converges`: http://docs.opscode.com/essentials_nodes_chef_run.html