FAQ document for Compose

Signed-off-by: Daniel Nephin <dnephin@docker.com>

docs/faq.md

@@ -0,0 +1,139 @@
+<!--[metadata]>
++++
+title = "Frequently Asked Questions"
+description = "Docker Compose FAQ"
+keywords = "documentation, docs,  docker, compose, faq"
+[menu.main]
+parent="smn_workw_compose"
+weight=9
++++
+<![end-metadata]-->
+
+# Frequently asked questions
+
+If you don’t see your question here, feel free to drop by `#docker-compose` on
+freenode IRC and ask the community.
+
+## Why do my services take 10 seconds to stop?
+
+Compose stop attempts to stop a container by sending a `SIGTERM`. It then waits
+for a [default timeout of 10 seconds](./reference/stop.md).  After the timeout,
+a `SIGKILL` is sent to the container to forcefully kill it.  If you
+are waiting for this timeout, it means that your containers aren't shutting down
+when they receive the `SIGTERM` signal.
+
+There has already been a lot written about this problem of
+[processes handling signals](https://medium.com/@gchudnov/trapping-signals-in-docker-containers-7a57fdda7d86)
+in containers.
+
+To fix this problem, try the following:
+
+* Make sure you're using the JSON form of `CMD` and `ENTRYPOINT`
+in your Dockerfile.
+
+  For example use `["program", "arg1", "arg2"]` not `"program arg1 arg2"`.
+  Using the string form causes Docker to run your process using `bash` which
+  doesn't handle signals properly. Compose always uses the JSON form, so don't
+  worry if you override the command or entrypoint in your Compose file.
+
+* If you are able, modify the application that you're running to
+add an explicit signal handler for `SIGTERM`.
+
+* If you can't modify the application, wrap the application in a lightweight init
+system (like [s6](http://skarnet.org/software/s6/)) or a signal proxy (like
+[dumb-init](https://github.com/Yelp/dumb-init) or
+[tini](https://github.com/krallin/tini)).  Either of these wrappers take care of
+handling `SIGTERM` properly.
+
+## How do I run multiple copies of a Compose file on the same host?
+
+Compose uses the project name to create unique identifiers for all of a
+project's  containers and other resources. To run multiple copies of a project,
+set a custom project name using the [`-p` command line
+option](./reference/docker-compose.md) or the [`COMPOSE_PROJECT_NAME`
+environment variable](./reference/overview.md#compose-project-name).
+
+## What's the difference between `up`, `run`, and `start`?
+
+Typically, you want `docker-compose up`. Use `up` to start or restart all the
+services defined in a `docker-compose.yml`. In the default "attached"
+mode, you'll see all the logs from all the containers. In "detached" mode (`-d`),
+Compose exits after starting the containers, but the containers continue to run
+in the background.
+
+The `docker-compose run` command is for running "one-off" or "adhoc" tasks. It
+requires the service name you want to run and only starts containers for services
+that the running service depends on. Use `run` to run tests or perform
+an administrative task such as removing or adding data to a data volume
+container. The `run` command acts like `docker run -ti` in that it opens an
+interactive terminal to the container and returns an exit status matching the
+exit status of the process in the container.
+
+The `docker-compose start` command is useful only to restart containers
+that were previously created, but were stopped. It never creates new
+containers.
+
+## Can I use json instead of yaml for my Compose file?
+
+Yes. [Yaml is a superset of json](http://stackoverflow.com/a/1729545/444646) so
+any JSON file should be valid Yaml.  To use a JSON file with Compose,
+specify the filename to use, for example:
+
+```bash
+docker-compose -f docker-compose.json up
+```
+
+## How do I get Compose to wait for my database to be ready before starting my application?
+
+Unfortunately, Compose won't do that for you but for a good reason.
+
+The problem of waiting for a database to be ready is really just a subset of a
+much larger problem of distributed systems. In production, your database could
+become unavailable or move hosts at any time.  The application needs to be
+resilient to these types of failures.
+
+To handle this, the application would attempt to re-establish a connection to
+the database after a failure. If the application retries the connection,
+it should eventually be able to connect to the database.
+
+To wait for the application to be in a good state, you can implement a
+healthcheck. A healthcheck makes a request to the application and checks
+the response for a success status code. If it is not successful it waits
+for a short period of time, and tries again. After some timeout value, the check
+stops trying and report a failure.
+
+If you need to run tests against your application, you can start by running a
+healthcheck. Once the healthcheck gets a successful response, you can start
+running your tests.
+
+
+## Should I include my code with `COPY`/`ADD` or a volume?
+
+You can add your code to the image using `COPY` or `ADD` directive in a
+`Dockerfile`.  This is useful if you need to relocate your code along with the
+Docker image, for example when you're sending code to another environment
+(production, CI, etc).
+
+You should use a `volume` if you want to make changes to your code and see them
+reflected immediately, for example when you're developing code and your server
+supports hot code reloading or live-reload.
+
+There may be cases where you'll want to use both. You can have the image
+include the code using a `COPY`, and use a `volume` in your Compose file to
+include the code from the host during development. The volume overrides
+the directory contents of the image.
+
+## Where can I find example compose files?
+
+There are [many examples of Compose files on
+github](https://github.com/search?q=in%3Apath+docker-compose.yml+extension%3Ayml&type=Code).
+
+
+## Compose documentation
+
+- [Installing Compose](install.md)
+- [Get started with Django](django.md)
+- [Get started with Rails](rails.md)
+- [Get started with WordPress](wordpress.md)
+- [Command line reference](./reference/index.md)
+- [Compose file reference](compose-file.md)

docs/index.md

@@ -59,6 +59,7 @@ Compose has commands for managing the whole lifecycle of your application:
 - [Get started with Django](django.md)
 - [Get started with Rails](rails.md)
 - [Get started with WordPress](wordpress.md)
+- [Frequently asked questions](faq.md)
 - [Command line reference](./reference/index.md)
 - [Compose file reference](compose-file.md)
 

script/travis/render-bintray-config.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python
+from __future__ import print_function
+
 import datetime
 import os.path
 import sys
 
 os.environ['DATE'] = str(datetime.date.today())
 
 for line in sys.stdin:
-    print os.path.expandvars(line),
+    print(os.path.expandvars(line), end='')