Improvements to documentation and ponyd installation

Improved and finished several features:

* devtools installation is done inside the virtualenv now
* better symlink error handling
* made pony listen on localhost by default
* Updated documentation

README_ponyd.rst

@@ -1,41 +1,99 @@
-
-PonyGateway: PonyDebugger Gateway Server
-========================================
+PonyGateway: PonyDebugger Gateway Server (``ponyd``)
+====================================================
 
 This directory contains the gateway server that serves Chrome Developer Tools.
 
-PonyGateway is licensed under the Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html).
+PonyGateway is licensed under the Apache Licence, Version 2.0
+(http://www.apache.org/licenses/LICENSE-2.0.html).
 
 Installing
 ----------
 
-- To install the latest stable version:
+There are two ways to install both are pretty simple and can be run in userland.
+The end result is the same.
+
+Quick userland install
+``````````````````````
+
+::
+
+  curl -sk https://cloud.github.com/downloads/square/PonyDebugger/bootstrap-ponyd.py | \
+    python - --ponyd-symlink=/usr/local/bin/ponyd ~/Library/PonyDebugger
+
+This will install ``ponyd`` script to ``~/Library/PonyDebugger/bin/ponyd`` and
+attempt to symlink ``/usr/local/bin/ponyd`` to it.
+
+This installer uses a `virtualenv
+<http://www.virtualenv.org/en/latest/index.html>`_ bootstrap script to install
+PonyDebugger and all its dependencies in an isolated python environment in
+``~/Library/PonyDebugger``.
+
+Since this uses virtualenv, you can also download the script and customize the
+installation options::
+
+  curl -O https://cloud.github.com/downloads/square/PonyDebugger/bootstrap-ponyd.py
+  python bootstrap-ponyd.py --help
+
+Upgrading your installation can be done with the following commands::
+
+  # activate your virtualenv
+  source ~/Library/PonyDebugger/bin/activate
+  # update the ponyd source
+  pip install -U -e git+https://github.com/square/PonyDebugger.git#egg=ponydebugger
+  # updates chrome dev tools source
+  ponyd update-devtools     
+
+.. Note:: This process will be simplified in the future
+
+
+Development installation
+````````````````````````
+
+If you already have PonyDebugger git repo checked out you can can set up a
+virtualenv manually and have your ponyd installation point to your existing
+checkout.  For demonstration we assume ``$VENV`` is set to your intended install
+path and ``$PONYDEBUGGER_PATH`` is set to your PonyDebugger git checkout::
+
+  # if you don't already have virtualenv installed
+  sudo easy_install virtualenv
+
+  virtualenv "$VENV"
+  source "$VENV/bin/activate"
+  pip install -e "$PONYDEBUGGER_PATH"
+
+  # to ensure your shell knows ponyd exists
+  hash -r
+
+To run this ponyd you can either activate your environment by ``source
+"$VENV/bin/activate"`` and ``ponyd`` will be added to your path.  You can also
+just call it directly via ``$VENV/bin/ponyd`` without activating first.
 
-  ``sudo pip install ponygateway``
 
-  Or omit sudo if installing in a virtual environment.
+Starting Debugging Server
+-------------------------
 
-  **Note**: If you want to download the latest version, you will have to clone the repository and run ``sudo python setup.py install`` in the ``ponygateway`` directory.
+Once installed, running PonyDebugger's server is easy::
 
-- Install a supported version of Chrome Developer Tools with ``ponydownloader``.
+  ponyd serve
 
-  This will install a supported version of Chrome Developer Tools into ``~/.devtools`` by default. To specify a custom directory:
+By default, ponyd listens on port 9000 and only on your localhost for security
+reasons.
 
-  ``ponydownloader /path/to/devtools``
+To make the server accessible by another device or computer you must have ponyd
+listen on ``0.0.0.0`` which is done by::
 
-- To run the Gateway server, run ``ponygateway``. By default, this will run the 
-  gateway on ``localhost:9000``.  
-
-  To specify a custom devtools directory:
+  ponyd serve -i 0.0.0.0
 
-  ``ponygateway -d /path/to/devtools``
+The listen and other ports can be customized as well.  Run ``ponyd serve
+--help`` for more information.
 
-  For more details, run ``ponygateway -h``
 
 Known Issues / Improvements
 ---------------------------
 
-- Relaunching the client application requires you to navigate back to the main page.
-- Chrome Developer Tools shows some unnecessary tabs (such as Elements).  ``ponydownloader`` could possibly be
-  updated to patch the incoming chrome developer tools to hide these unused tabs.
+- Relaunching the client application requires you to navigate back to the main
+  page.
+- Chrome Developer Tools shows some unnecessary tabs (such as Elements).
+  ``ponyd update-devtools`` could possibly be updated to patch the incoming
+  chrome developer tools to hide these unused tabs.
 

ponyd/constants.py

@@ -1,5 +1,5 @@
 
 import os
+import sys
 
-DEFAULT_DEVTOOLS_PATH = os.path.expanduser('~/.devtools')
-
+DEFAULT_DEVTOOLS_PATH = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(sys.argv[0])), '..', 'src', 'devtools'))

ponyd/downloader.py

@@ -18,24 +18,13 @@ class Downloader(PonydCommand):
     __subcommand__  = 'update-devtools'
 
     dirname = Arg(nargs='?',
-                  help='path to download and extract devtools',
+                  help='path to download and extract devtools (default: %s)' % DEFAULT_DEVTOOLS_PATH,
                   default=DEFAULT_DEVTOOLS_PATH)
-    force = Arg('-f', '--force',
-                help='if dirname already exists, then replace directory',
-                action='store_true')
     latest = Arg('-l', '--latest',
                  help='install the lastest dev tools instead of a known good version',
                  action='store_true')
 
     def __call__(self):
-        if os.path.exists(self.dirname):
-            if self.force:
-                print "Removing directory", os.path.abspath(self.dirname)
-                shutil.rmtree(self.dirname)
-            else:
-                print "Directory %s exists. Run with --force (-f) to overwrite the directory." % self.dirname
-                return
-
         if self.latest:
             version = urllib2.urlopen(LATEST_URL).read()
         else:
@@ -46,9 +35,15 @@ def __call__(self):
 
         tools_stream = StringIO(urllib2.urlopen(tools_url).read())
 
+
+        if os.path.exists(self.dirname):
+            print "Removing existing devtools installation at %s" % self.dirname
+            shutil.rmtree(self.dirname)
+
         extract_dir = self.dirname
         print "Extracting to %s" % extract_dir
 
         tools_zip = zipfile.ZipFile(tools_stream, 'r')
         tools_zip.extractall(path=extract_dir)
 
+

ponyd/gateway.py

@@ -63,7 +63,8 @@ def devToolsConnected(self, devTools):
             if device.page == devTools.page:
                 devTools.waiting = False
 
-                logger.info("Dev tools connecting to device %s", device.deviceID)
+                logger.info("Dev tools connecting to device %s",
+                            device.deviceID)
                 devTools.device = device
                 device.devTools = devTools
                 break
@@ -123,7 +124,9 @@ def _registerDevice(self, params):
         self.app_state.registerDevice(self)
 
         # Announce existence.
-        logger.info("Device %s Registered (%s, %s)" % (self.deviceID, self.device_model, self.device_name))
+        logger.info("Device %s Registered (%s, %s)" % (self.deviceID,
+                                                       self.device_model,
+                                                       self.device_name))
 
     @property
     def deviceInfo(self):
@@ -207,7 +210,7 @@ class Gateway(PonydCommand):
 
     listen_interface = Arg('-i', '--listen-interface',
                            help='interface to listen on. [default: %(default)s]',
-                           default='0.0.0.0',
+                           default='127.0.0.1',
                            metavar='IFACE')
 
     def __call__(self):

scripts/_bootstrap_contents.py

@@ -11,12 +11,20 @@ def after_install(options, home_dir):
 
     ponyd_path = join(home_dir, 'bin', 'ponyd')
 
-    if options.ponyd_symlink:
+
+    symlink_target = options.ponyd_symlink
+
+    if symlink_target:
+        if os.path.isdir(symlink_target):
+            symlink_target  = os.path.join(symlink_target, 'ponyd')
+
+        if os.path.exists(symlink_target):
+            print "Symlink to %s already exists. (continuing anyways)" % symlink_target
         try:
-            print "Symlinking %s to %s" % (ponyd_path, options.ponyd_symlink)
-            os.symlink(ponyd_path, options.ponyd_symlink)
+            print "Symlinking %s to %s" % (ponyd_path, symlink_target)
+            os.symlink(ponyd_path, symlink_target)
         except:
-            print >>sys.stderr, "Error creating symlink" 
+            print >>sys.stderr, "Error creating symlink. Manually run: sudo ln -s '%s' '%s'" % (ponyd_path, symlink_target)
 
     subprocess.check_call([ponyd_path, 'update-devtools'])