Adds rationale for healthcheck config (#2812)

As we routinely get FUD about slow startup or memory usage, this
documents health check parameters in efforts to avoid them being read
literally as "zipkin takes 30s to startup"

See #2808

docker/Dockerfile

@@ -38,7 +38,32 @@ USER zipkin
 
 EXPOSE 9410 9411
 
+# This health check was added for Docker Hub automated test service. Parameters
+# were changed in order to mark success faster. You may want to change these
+# further in production.
+#
+#
+# By default, the Docker health check runs after 30s, and if a failure occurs,
+# it waits 30s to try again. This implies a minimum of 30s before the server is
+# marked healthy.
+#
 # https://docs.docker.com/engine/reference/builder/#healthcheck
+#
+# We expect the server startup to take less than 10 seconds, even in a fresh
+# start. Some health checks will trigger a slow "first request" due to schema
+# setup (ex this is the case in Elasticsearch and Cassandra). However, we don't
+# want to force an initial delay of 30s as defaults would.
+#
+# Instead, we lower the interval and timeout from 30s to 5s. If a server starts
+# in 7s and takes another 2s to install schema, it can still pass in 10s vs 30s.
+#
+# We retain the 30s even if it would be an excessively long startup. This is to
+# accomodate test containers, which can boot slower than production sites, and
+# any knock-on effects of that, like slow dependent storage containers which are
+# simultaneously bootstrapping. If in production, you have a 30s startup, please
+# report to https://gitter.im/openzipkin/zipkin including the values of the
+# /health and /info endpoints as this would be unexpected.
+#
 HEALTHCHECK --interval=5s --start-period=30s --timeout=5s CMD wget --quiet http://localhost:9411/health || exit 1
 
 ENTRYPOINT ["/busybox/sh", "run.sh"]