Adds static content docs

This adds static content configuration docs, and adds it as a component
in the architecture list. It adds a single step to the installer which
refers to the more detailes docs.

It also adds the 'DEBUG: False' as the default to settings.yaml which
was missing. It was needed because these docs mention configuring it
there.

It also makes a few formatting improvements.

https://pulp.plan.io/issues/3620
closes #3620

docs/installation/instructions.rst

@@ -11,11 +11,13 @@ Fedora, CentOS, and Mac OSX.
 .. note::
 
     As Pulp 3 currently does not have an SELinux Policy, it currently requires the target
-    machine to have SELinux set to permissive mode or disabled. If you are not sure if the system is capabable or is currently running SELinux run the following command:
+    machine to have SELinux set to permissive mode or disabled. If you are not sure if the system is
+    capable or is currently running SELinux run the following command::
 
     $ getenforce
 
-    If the command is not found or the return status is "Permissive" or "Disabled" then skip to step 1. If the return of the command is "Enforcing" then this next command should be applied:
+    If the command is not found or the return status is "Permissive" or "Disabled" then skip to step
+    1. If the return of the command is "Enforcing" then this next command should be applied::
 
     $ sudo setenforce 0
 
@@ -97,7 +99,13 @@ PyPI Installation
    $ pulp-manager migrate --noinput
    $ pulp-manager reset-admin-password --password admin
 
-10. Run Pulp:
+10. Collect and Serve Static Media
+
+   Pulp will operate correctly without static media being served, but if browsing the Pulp API with
+   a web browser you probably want to configure it. See :ref:`static-content` for more info on
+   collecting and serving static content.
+
+11. Run Pulp:
 ::
 
    $ django-admin runserver

docs/overview/components/index.rst

@@ -18,8 +18,11 @@ Queue
 SQL Database
   Refer to the database documentation on how to scale it and/or make it highly available.
 
+Static Content
+  Pulp's browsable api uses some static content.  See the :ref:`static-content` docs for more info
+  on deploying and scaling this component.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    webserver

docs/overview/components/webserver.rst

@@ -24,4 +24,38 @@ Plugin Views
 
 Using the urls above you can choose which webservers and how many will serve the different parts of
 the Pulp application. If you want to have a single rule to serve all components of the Pulp web
-application, routing ``/`` to it will is simple and will always work.
+application, routing ``/`` to it is simple and will always work.
+
+.. _static-content:
+
+Static Content
+==============
+
+When browsing the REST API or the browsable documentation with a web browser, for a good experience,
+you'll need static content to be served.
+
+In Development
+--------------
+
+If using the built-in Django webserver and your settings.yaml has ``DEBUG: True`` then static
+content is automatically served for you.
+
+In Production
+-------------
+
+For production environments, configure static content as follows:
+
+1. Pick the URL static content is served at, e.g. ``/static/`` and set that as the STATIC_URL in the
+settings.yaml file. Then select the path on the local filesystem where static content will be
+stored, and set that as STATIC_ROOT.
+
+2. Configure your webserver to serve the STATIC_ROOT directory's contents at the STATIC_URL url.
+
+3. Once configured, collect all of the static content into place using the ``collectstatic`` command
+as follows::
+
+    $ pulp-manager collectstatic
+
+For more information on scaling your static content, configuring object storage to serve your static
+media, and other topics refer to the
+`Django Static Media docs <https://docs.djangoproject.com/en/2.0/howto/static-files/deployment/>`_

pulpcore/pulpcore/etc/pulp/server.yaml

@@ -38,6 +38,11 @@ databases:
 #
 # SECRET_KEY:
 
+# `DEBUG`: A boolean that turns on/off debug mode. See the Django docs for more information on the
+# behaviors this affects.
+#
+# DEBUG: False
+
 # `MEDIA_ROOT`: Location where Pulp stores files (Artifacts, published metadata, etc)
 #
 # MEDIA_ROOT: /var/lib/pulp/