Table of Contents
Services, Networks, and Volumes Together
In a Docker Compose file, the most powerful part is how services, networks, and volumes fit together. This chapter focuses on how to describe these three elements in docker-compose.yml so they work as a single, reproducible application.
You already know what Docker Compose is and what a docker-compose.yml is for. Now you will learn how to structure the definitions inside it.
The `services` Section
Every Compose file centers around the services section. Each entry under services describes one containerized component of your application, for example a web server, a database, or a background worker.
A service definition usually includes the image or build context it uses, optional configuration such as ports and environment variables, and how it connects to networks and volumes. Although this chapter does not fully explain every possible field, it shows how they relate to networks and volumes.
Inside services, you assign a name to each service. This name is important, because it will be used as a DNS hostname inside custom networks and is also how you interact with it using Compose commands. For example, if your service is called web, other services on the same network can reach it using the hostname web.
The service name also serves as a logical grouping for all the configuration that belongs to that container. When you later scale or restart services with Compose, you always work with these names.
The `networks` Section
Below or above services, you can define application networks in a top level networks section. These are logical Docker networks that Compose creates or reuses for your project.
Each network in networks gets a name that you choose. This is not the same as the low level Docker bridge networks you might have seen earlier. Compose manages these for you and uses the names you assign inside the file.
Networks can be very simple. You can just declare a name and let Docker use its defaults. You can also make them more explicit by choosing a driver or other options, but those details are outside the focus of this chapter.
The key point is that the networks section only defines what networks exist for this application. It does not attach any container to them yet. That attachment happens inside the services section.
The `volumes` Section
In a similar way, a top level volumes section defines data volumes that belong to your application. These are named volumes created and managed by Docker, not host directory bind mounts.
Inside volumes, you choose volume names. These names are project scoped, which means Compose treats them as resources belonging to your application stack. Like networks, you can either accept default settings or configure more advanced options if needed.
The volumes section only describes which named volumes exist. It does not say which service will use them or where they will be mounted inside the container. That connection is configured within each service.
Linking Services to Networks
A service uses networks through its own networks subsection. There, you list one or more network names that must already be declared in the top level networks section or be implicitly created by Compose.
The order in which you list networks for a service matters for some advanced behaviors, but for most simple cases it is enough to know that each named network provides:
Service discovery inside that network. Services can reach each other using the service names as hostnames. You do not have to specify IP addresses.
Network isolation from other networks. If two services are on different networks that do not overlap, they cannot see each other directly.
You can attach a service to multiple networks if it needs to communicate with components that should not all share a single network. In that case, the service gets one network interface per network and can reach services on each one as long as name resolution is available.
If a service does not explicitly list any networks, Compose usually connects it to a default network for the project. Defining your own networks gives you more control over which services can talk to each other.
Important rule: A network must exist at the top level of the Compose file or be implicitly created, and a service must list that network under its networks key to be attached to it.
Linking Services to Volumes
A service uses volumes through its volumes subsection. Each entry in this list describes how a volume or host path appears inside the container file system.
For named volumes, the left part of the mapping uses a volume name that matches a definition in the top level volumes section. The right part is the path inside the container where this data will be available. This path is entirely up to you and your application, but it must match where the application expects to read or write data.
Named volumes defined at the top level and used by multiple services allow you to share data between containers in a controlled way. For example, a web service and a worker service can both read from and write to the same Docker managed storage without exposing it directly from the host file system.
If you specify a volume in a service without declaring it in the top level volumes section, Compose can create it implicitly as a named volume. Declaring volumes explicitly is often clearer, especially in larger configurations, because it documents which persistent resources your stack needs.
Important rule: The volume name in a service volume mapping must either match a name in the top level volumes section or be implicitly created. The container path is where the data will appear inside that specific service.
How Services, Networks, and Volumes Interact
When Docker Compose starts your application, it reads the services, networks, and volumes sections and performs a sequence of operations.
First, it ensures that the defined networks exist. If they are not present yet, it creates them according to the configuration in the top level networks section. Next, it ensures that named volumes exist, creating them as described in the top level volumes section or using defaults.
After the networks and volumes are ready, Compose creates and starts the containers defined in services. While creating each container, Compose connects it to the listed networks and attaches the listed volumes, mounting them at the paths you provided.
Because networks and volumes are created at the project level, they can outlive individual containers. For example, you can stop and recreate a service and still keep its data, as long as you defined a named volume for it. You can also add or remove services that join existing networks, as long as the Compose file references the same network names.
The structure in the Compose file therefore provides a kind of blueprint. Services describe the running containers, networks describe how those containers communicate, and volumes describe how data persists.
Naming and Project Scope
Compose groups all defined services, networks, and volumes under a project. The default project name is often the directory name that contains the docker-compose.yml file, unless you override it with environment variables or options.
Internally, Docker prefixes network and volume names with this project name, even if you only see the simple names in the Compose file. This prevents resource collisions when you deploy multiple stacks that might use the same logical names.
For your purposes when editing docker-compose.yml, you usually only write the simple names. Compose takes care of translating them into globally unique Docker object names on your system, scoped to the project.
This scoping behavior explains why the same Compose file can be used in different environments without changing network and volume names. Each environment simply uses its own project name, and the resources are kept separate.
Evolving the Definitions Over Time
In a real application, you rarely get the services, networks, and volumes exactly right the first time. You may start with a single network and a single volume, then later introduce extra networks for isolation or more volumes for specific components.
When you adjust the top level networks or volumes sections, you must also update the services section so each service still references valid names. If you remove a network from the top level without updating a service that uses it, Compose will fail to start until you fix the mismatch.
Similar care is needed when renaming items. If you rename a network or volume in the top level sections, you must update all services that reference that name. Otherwise, Compose will treat the new name as a different resource and may silently create a new volume instead of using the old one.
The structure of services, networks, and volumes encourages you to think of your application as a whole. Whenever you add a new component, you decide which existing networks it should join and whether it should reuse existing volumes or need new ones.
Summary of Relationships
At the core of Compose configuration is a clear relationship between services, networks, and volumes. Services represent running containers. Networks are the communication channels that services join. Volumes are the persistent storage units that services mount inside their file systems.
You define networks and volumes at the top level as shared resources. You then attach them to services through each service configuration. This pattern lets you describe complex applications in a file that is still readable and maintainable, while keeping communication paths and data persistence explicit.