Docker Compose Tutorial: Start, Stop, and Validate YAML

Docker Compose manages a multi-container application from a Compose file such as compose.yaml. Use docker compose up to create and start services, docker compose stop to stop them while keeping the containers, and docker compose down to remove the project containers and network.

Before you begin

Make sure Docker Desktop or Docker Engine is running. Open a terminal and create or enter a project folder. Every Compose command in this guide should be run from the folder that contains your Compose file, unless you use the -f option to provide another path.

mkdir compose-demo
cd compose-demo

On Windows PowerShell or Command Prompt, the same commands work. You can also create the folder with File Explorer and then use cd to enter it.

Create a small Compose file

Create a file named compose.yaml with this content:

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
  redis:
    image: redis:7-alpine

This defines two services. The web service publishes NGINX at http://localhost:8080. The redis service is reachable by other services on the Compose network using the hostname redis.

Validate the file with docker compose config

docker compose config reads your YAML file and prints the configuration that Compose will actually use. It expands variables, checks the YAML structure, and makes defaults easier to see. It does not start containers and it does not change your files.

Run it from the folder that contains compose.yaml:

docker compose config

Expected result: you should see a longer YAML document containing services, web, redis, the NGINX image, the Redis image, and the published port. Seeing the resolved configuration means Compose could parse the file.

To validate without printing the full resolved YAML, use:

docker compose config --quiet

A successful command returns to the prompt without an error. If validation fails, Compose prints the problem.

Fix “no configuration file provided”

If you see:

no configuration file provided: not found

Compose did not find a file with one of its default names in the current folder. The usual default names are compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml.

On Windows Command Prompt, list YAML files in the current folder:

dir /b *.yml *.yaml

If the file has a different name, select it with -f. For example, if the file is called wordpress.yml:

docker compose -f wordpress.yml config --quiet

If the file is in a subfolder:

docker compose -f ".dockerwordpress.yml" config --quiet

If you need to use a full Windows path, replace the placeholder with your own path and keep the quotation marks:

docker compose -f "C:path	osite1wordpress.yml" config --quiet

You can omit --quiet when you want to see the resolved configuration:

docker compose -f wordpress.yml config

Use multiple Compose files

When a project has a base file and an override file, list them in order:

docker compose -f base.yml -f wordpress.yml config --quiet

Compose combines the files, and values in the later file override or extend matching values from the earlier file. Keep paths relative to the first Compose file and test the combined result with docker compose ... config before starting services.

Start the application

docker compose up

This creates the service containers and attaches your terminal to their combined output. Keep this terminal open while you test the application. Press Ctrl+C to stop the attached application.

For background mode:

docker compose up -d

The -d option leaves the services running after the terminal is available again. Open http://localhost:8080 to verify the web service.

Check service status

docker compose ps

This lists the project’s services, container state, and published ports. A running service normally shows a status such as Up. Use docker compose logs if a service is not healthy or exits.

Stop services but keep them

docker compose stop

This stops the service containers without removing them. Start them again with:

docker compose start

This is useful when you want to pause local development and preserve the existing containers.

Restart services

docker compose restart

Restarting stops and starts the existing service containers. It does not rebuild images or recreate containers.

Stop and remove the project

docker compose down

This stops and removes the project containers and networks created by Compose. Named volumes are not removed by default.

Start after changing YAML

docker compose up -d

Compose compares the current file with the existing service configuration and may recreate affected containers. Mounted volumes are preserved, but data stored only in a container’s writable layer should not be treated as persistent. Use --build when a service image must be rebuilt from a Dockerfile:

docker compose up -d --build

Common mistakes

• Running commands from the wrong folder. Use cd or the -f option.
• Using docker-compose when your installation provides modern Compose V2 as docker compose.
• Assuming config starts containers. It only validates and renders configuration.
• Assuming stop deletes containers. It does not.
• Using down -v without checking persistent data.

Official references

See Docker’s Compose CLI reference, Compose up, and Compose down documentation.