Update getting started docs

docs/development/getting-started.rst

@@ -26,18 +26,6 @@ so we can improve the process:
 - For longer-form questions or discussion, message the `pypa-dev mailing
   list`_.
 
-
-Quickstart for Developers with Docker experience
-------------------------------------------------
-.. code-block:: console
-
-    git clone git@github.com:pypa/warehouse.git
-    cd warehouse
-    make serve
-    make initdb
-
-View Warehouse in the browser at ``http://localhost:80/``.
-
 .. _dev-env-install:
 
 Detailed Installation Instructions
@@ -107,6 +95,22 @@ Verifying Docker Compose Installation
 Check that Docker Compose is installed: ``docker-compose -v``
 
 
+Verifying the Neccessary Ports are Available
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Warehouse needs access to a few local ports in order to run, namely ports
+``80``, ``5433``, and ``9000``. You can check if a port is in use by running
+the following command (in this example, checking port ``80``:
+
+.. code-block:: console
+
+    lsof -i:80 | grep LISTEN
+
+If the port is in use, the command will produce output, and you will need to
+determine what is occupying the port and shut down the service. Otherwise, the
+port is available for Warehouse to use, and you can continue.
+
+
 Building the Warehouse Container
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -134,41 +138,61 @@ increase the memory allocated to Docker in
 or `Docker Settings <https://docs.docker.com/docker-for-windows/#advanced>`_
 (on Windows) by moving the slider to 4 GB in the GUI.
 
-Then, in one terminal run the command:
+Then, in a terminal run the command:
 
 .. code-block:: console
 
     make serve
 
-Next, you will:
+This command will produce output for a while, and will not exit. While it runs,
+open a second terminal, and run:
+
+.. code-block:: console
+
+    make initdb
+
+This command will:
 
 * create a new Postgres database,
 * install example data to the Postgres database,
-* run migrations, and
-* load some example data from `Test PyPI`_
-
-In a second terminal, separate from the ``make serve`` command above, run:
+* run migrations,
+* load some example data from `Test PyPI`_, and
+* index all the data for the search database.
 
-.. code-block:: console
+.. note::
 
-    make initdb
+    If you get an error about xz, you may need to install the ``xz`` utility.
+    This is highly likely on Mac OS X and Windows.
 
-If you get an error about xz, you may need to install the ``xz`` utility. This
-is highly likely on Mac OS X and Windows.
+Once the ``make initdb`` command has finished, you are ready to continue.
 
 
 Viewing Warehouse in a browser
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Once the terminal running the ``make serve`` command has logged that a
-``web`` service has started listening:
+Eventually the output of the ``make serve`` command will cease, and you will
+see a log message indicating that either the ``web`` service has started
+listening:
+
+.. code-block:: console
+
+    web_1 | [2018-05-01 20:28:14 +0000] [6] [INFO] Starting gunicorn 19.7.1
+    web_1 | [2018-05-01 20:28:14 +0000] [6] [INFO] Listening at: http://0.0.0.0:8000 (6)
+    web_1 | [2018-05-01 20:28:14 +0000] [6] [INFO] Using worker: sync
+    web_1 | [2018-05-01 20:28:14 +0000] [15] [INFO] Booting worker with pid: 15
+
+or that the ``static`` container has finished compiling the static assets:
 
 .. code-block:: console
 
-    web_1 | [2018-04-30 22:40:43 +0000] [6] [INFO] Listening at: http://0.0.0.0:8000
+    static_1 | [20:28:37] Starting 'dist:compress'...
+    static_1 | [20:28:37] Finished 'dist:compress' after 14 μs
+    static_1 | [20:28:37] Finished 'dist' after 43 s
+    static_1 | [20:28:37] Starting 'watch'...
+    static_1 | [20:28:37] Finished 'watch' after 11 ms
 
-the web container is listening on port 80. It's accessible at
-``http://localhost:80/``.
+This means that all the services are up, and web container is listening on port
+80. It's accessible at ``http://localhost:80/``.
 
 .. note::