5.8 KiB

Raw Blame History

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. 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 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) or a signal proxy (like dumb-init or 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 or the COMPOSE_PROJECT_NAME environment variable.

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 so any JSON file should be valid Yaml. To use a JSON file with Compose, specify the filename to use, for example:

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.

5.8 KiB Raw Blame History Unescape Escape