compd

compd (or composed) is a program that spawns of a custom command while ensuring a docker-compose set of containers are running. It will wait for the containers to be started (and the programs within to be ready for requests, such as SQL databases), and (optionally) teardown the docker-composed containers. It forwards the exit code from the custom command and exits with the same exit code after the containers have been stopped.

Ports that are only specified on the container side (i.e. without hard-coded host ports) are deduced, and environment variables are provided to the running command. If a docker-compose file has a service called "redis" and a container port 6379, this will cause an environment variable to be created called REDIS_PORT_6379 with the value being the host port. If only one port is exposed, a shortcut environment variable without the the container port will be provided too, e.g. REDIS_PORT.

Since 4.0, compd will also detect the docker host (see below) and set _HOST environment variables accordingly, e.g. REDIS_HOST which is useful when this is not localhost.

Installation

Use compd by installing it globally:

npm install -g compd
# or with yarn
yarn global add compd

compd --file docker-compose.yaml my-app

or run through npx:

npx compd --file docker-compose.yaml my-app

Non-localhost docker

When running docker-in-docker in some setups, spinning up a container may not make it reachable on localhost, but on another IP. compd will (since 4.0) try to figure out this host by reading the DOCKER_HOST environment variable. If this doesn't work, you can:

• Set it to a custom one using --docker-host=host:1.2.3.4 or
• Set it to the value of an environment variable using --docker-host=env:{envvar} or
• Tell compd to detect it (by reading /sbin/ip route or route -n) using --docker-host=route.

Readiness detectors

When all host ports are deduced from the container ports, compd start scanning the ports to see if they are open. When they are, compd will try to deduce what potentially known services are being run (such as a redis server, a Postgres server etc) and will use different mechanisms for each type of server to detect if it is ready for requests. E.g. a Postgres port can be open, but the server not be available for requests immediately. It can take seconds for it to be ready.

The custom command won't be spawned until all ports with known servers are positively ready.

Current detectors

There is support for:

• Open TCP ports (before trying the below detectors)
• Redis
• Postgres