Merge pull request #1592 from bacongobbler/localdev-docs

Matthew Fisher · Matthew Fisher · commit efb4524139e8 · 2014-08-15T08:13:50.000-07:00
docs(contributing/localdev): update localdev docs
diff --git a/docs/contributing/localdev.rst b/docs/contributing/localdev.rst
@@ -4,53 +4,58 @@
 
 Local Development
 =================
-We try 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.
 
-If you're just getting into the Deis codebase, look for GitHub issues
-with the label `easy-fix`_. These are more straightforward or low-risk
-issues for which we need pull requests. Issues tagged `easy-fix`_ are a
-great way to become more familiar with Deis.
+We try to make it simple to hack on Deis. However, there are necessarily several moving
+pieces and some setup required. We welcome any suggestions for automating or simplifying
+this process.
+
+If you're just getting into the Deis codebase, look for GitHub issues with the label
+`easy-fix`_. These are more straightforward or low-risk issues for which we need pull
+requests. Issues tagged `easy-fix`_ are a great way to become more familiar with Deis.
 
 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.6+
  * VirtualBox 4.2+
 
 Fork the Repository
 -------------------
-To get Deis running locally, first `fork the Deis repository`_, 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 git@github.com:<username>/deis.git
 	$ cd deis
 	$ export DEIS_DIR=`pwd`  # to use in future commands
 
-Provision the Controller
-------------------------
-First bring up a virtual machine to host Deis. To share your local
-codebase into the CoreOS VM, Deis uses NFS mounts, so you will be
-prompted for an administrative password.
+Provision the Cluster
+---------------------
+
+First bring up a virtual machine to host Deis. To share your local codebase into the
+CoreOS VM, Deis uses rsync.
 
 .. code-block:: console
 
     $ vagrant up
-    Bringing machine 'deis' up with 'virtualbox' provider...
-    ==> deis: Importing base box 'coreos-alpha'...
-    ...
-    ==> deis: Exporting NFS shared folders...
-    ==> deis: Preparing to edit /etc/exports. Administrator privileges will be required...
-    Password:
-    ==> deis: Mounting NFS shared folders...
-    ...
-    ==> deis: Running provisioner: shell...
-    deis: Running: inline script
+    Bringing machine 'deis-1' up with 'virtualbox' provider...
+    ==> deis-1: Importing base box 'coreos-402.2.0'...
+    ==> deis-1: Matching MAC address for NAT networking...
+    ==> deis-1: Setting the name of the VM: deis_deis-1_1408039741706_8568
+    ==> deis-1: Clearing any previously set network interfaces...
+    ==> deis-1: Preparing network interfaces based on configuration...
+        deis-1: Adapter 1: nat
+        deis-1: Adapter 2: hostonly
+    ==> deis-1: Forwarding ports...
+        deis-1: 22 => 2222 (adapter 1)
+    ==> deis-1: Running 'pre-boot' VM customizations...
+    ==> deis-1: Booting VM...
+    ==> deis-1: Waiting for machine to boot. This may take a few minutes...
     $
 
 Set ``FLEETCTL_TUNNEL`` so the ``fleetctl`` client on your workstation can connect to the VM:
@@ -59,15 +64,16 @@ Set ``FLEETCTL_TUNNEL`` so the ``fleetctl`` client on your workstation can conne
 
     export FLEETCTL_TUNNEL=172.17.8.100
 
-Next, run ``make pull && make build`` to SSH into the VM, pull Deis'
-images from the Docker Index, then update those images with any local
-changes.
+Next, run ``make pull && make build`` to SSH into the VM, pull Deis' images from the
+Docker Index, then update those images with any local changes.
 
 .. code-block:: console
 
     $ make pull
-    vagrant ssh -c 'for c in registry logger database cache controller \
-      builder router; do docker pull deis/$c:latest; done'
+    for host in 172.17.8.100 ; do ssh -o LogLevel=FATAL -o Compression=yes \
+        -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        -o PasswordAuthentication=no core@$host \
+        -t 'for c in builder cache controller database logger registry router; do docker pull deis/$c:latest; done'; done
     Pulling repository deis/registry
     d2c347aa26dd: Pulling dependent layers
     511136ea3c5a: Download complete
@@ -77,9 +83,10 @@ changes.
     e5efa1477310: Download complete
     Connection to 127.0.0.1 closed.
     $ make build
-    vagrant ssh -c 'cd share && for c in registry logger database \
-      cache controller builder router; \
-      do cd $c && docker build -t deis/$c . && cd ..; done'
+    for host in 172.17.8.100 ; do ssh -o LogLevel=FATAL -o Compression=yes \
+        -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        -o PasswordAuthentication=no core@$host \
+        -t 'for c in builder cache controller database logger registry router; do cd $c && docker build -t deis/$c . && cd ..; done'; done
     Uploading context 22.53 kB
     Uploading context
     Step 0 : FROM deis/base:latest
@@ -93,24 +100,32 @@ changes.
     Successfully built cf4b7a398500
     Connection to 127.0.0.1 closed.
 
-Finally, do ``make run`` to start all Deis containers and displays their
-collected log output:
+Finally, do ``make run`` to start all Deis containers:
 
 .. code-block:: console
 
     $ make run
-    vagrant ssh -c 'cd share && for c in registry logger database \
-      cache controller builder router; \
-      do cd $c && sudo systemctl enable $(pwd)/systemd/* && cd ..; done'
-    ln -s '/home/core/share/registry/systemd/deis-registry.service' \
-      '/etc/systemd/system/multi-user.target.wants/deis-registry.service'
-    ...
-    Apr 15 18:53:23 deis sh[9101]: 2014-04-15 12:53:23 [149] [INFO] Booting worker with pid: 149
-    Apr 15 18:53:24 deis sh[9101]: [2014-04-15 12:53:24,842: INFO/MainProcess] mingle: all alone
-    Apr 15 18:53:24 deis sh[9101]: [2014-04-15 12:53:24,852: WARNING/MainProcess] celery@121f56ff9ae5 ready.
+    Job deis-router@1.service loaded on ff3442c2.../172.17.8.100
+    Job deis-builder-data.service loaded on ff3442c2.../172.17.8.100
+    Job deis-database-data.service loaded on ff3442c2.../172.17.8.100
+    Job deis-logger-data.service loaded on ff3442c2.../172.17.8.100
+    Job deis-registry-data.service loaded on ff3442c2.../172.17.8.100
+    fleetctl --strict-host-key-checking=false load logger/systemd/deis-logger.service cache/systemd/deis-cache.service database/systemd/deis-database.service
+    Job deis-cache.service loaded on ff3442c2.../172.17.8.100
+    Job deis-database.service loaded on ff3442c2.../172.17.8.100
+    Job deis-logger.service loaded on ff3442c2.../172.17.8.100
+    fleetctl --strict-host-key-checking=false load registry/systemd/*.service
+    Job deis-registry.service loaded on ff3442c2.../172.17.8.100
+    fleetctl --strict-host-key-checking=false load controller/systemd/*.service
+    Job deis-controller.service loaded on ff3442c2.../172.17.8.100
+    fleetctl --strict-host-key-checking=false load builder/systemd/*.service
+    Job deis-builder.service loaded on ff3442c2.../172.17.8.100
+    Deis components may take a long time to start the first time they are initialized.
+    Waiting for 1 of 1 deis-routers to start...
 
 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.
@@ -125,6 +140,7 @@ your local workstation.
 
 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.
 
@@ -138,31 +154,29 @@ receive full admin permissions.
     Registered myuser
     Logged in as myuser
 
-Once the user is registered, add your SSH key for ``git push``
-access using:
+Once the user is registered, add your SSH key for ``git push`` access using:
 
 .. code-block:: console
 
     $ deis keys:add
     Found the following SSH public keys:
     1) id_rsa.pub
     Which would you like to use with Deis? 1
-    Uploading /Users/myuser/.ssh/id_rsa.pub to Deis... done
-
+    Uploading /home/myuser/.ssh/id_rsa.pub to Deis... done
 
-Your local development environment is running! Follow the
-rest of the `_using_deis` guide to deploy your first application.
+Your local development environment is running! Follow the rest of the `_using_deis` guide
+to deploy your first application.
 
 Test Your Changes
 -----------------
-In the single-node Vagrant environment, testing your changes to Deis itself
-is easy:
 
-    - Make changes to the code in one of the component subdirectories, such
-      as ``controller/``
-    - run ``make -C controller/ build run``
-    - Test your changes with ``make -C controller/ test`` and interactively
-      with the Deis client
+In the single-node Vagrant environment, testing your changes to Deis itself is easy!
+
+- Make changes to the code in one of the component subdirectories, such as
+  ``controller/``
+- run ``make -C controller/ build run``
+- Test your changes with ``make -C controller/ test-unit`` and interactively with the
+  Deis client
 
 Useful Commands
 ---------------
@@ -174,24 +188,28 @@ Tail Logs
 
 .. code-block:: console
 
-    $ vagrant ssh -c 'sudo docker logs --follow=true deis-controller'
+    $ vagrant ssh -c 'docker logs -f deis-controller'
+
+Rebuild Services from Source
+````````````````````````````
+
+    $ make -C controller build
 
 Restart Services
 ````````````````
 
 .. code-block:: console
 
-    $ vagrant ssh -c 'sudo restart deis-controller'
+    $ make -C controller restart
 
 Django Admin
 ````````````
 
 .. code-block:: console
 
     $ vagrant ssh              # SSH into the controller
-    $ sudo su deis -l          # change to deis user
-    $ cd controller            # change into the django project root
-    $ source venv/bin/activate # activate python virtualenv
+    $ nse deis-controller      # inject yourself into the container
+    $ cd /app                  # change into the django project root
     $ ./manage.py shell        # get a django shell
 
 Have commands other Deis developers might find useful? Send us a PR!
@@ -200,9 +218,9 @@ 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
-that test coverage has improved as a result of your changes and new unit tests.
+Specifically, when you change local code, you must run ``make flake8 && make coverage``,
+then check the HTML report to see that test coverage has improved as a result of your
+changes and new unit tests.
 
 .. code-block:: console
 
@@ -232,8 +250,9 @@ 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.
 
-Creating a pull request on the Deis repository also runs a Travis CI build to
-ensure the pull request doesn't break any tests or reduce code coverage.
+Creating a pull request on the Deis repository also runs an integration test on
+http://ci.deis.io to ensure the pull request doesn't break any tests or reduce code
+coverage.
 
 
 .. _`easy-fix`: https://github.com/deis/deis/issues?labels=easy-fix&state=open
