A docker-compose stack (or fleet of stacks on one host) has inconsistent container/volume/network naming — some services use hardcoded container_name/name: overrides (producing underscore-separated names like jupyter_hub, jupyter_ollama_data), while others rely on Compose's default naming and use hyphenated project names (e.g. digiiq-ceronica-blue), producing hyphenated container names like digiiq-ceronica-blue-insights-blue-1. How do you make naming consistent, and is it safe to just remove the overrides?
Fix: Compose's default naming behavior differs by resource type, and this matters for how you fix inconsistent naming: - Containers: default name is `<project>-<service>-<replica>` (hyphen-joined). Simply removing an explicit `container_name:` override is enough to get this — Compose matches existing containers to services via internal labels (com.docker.compose.project/service), not by the container_name string, so on the next `up -d` it safely stops the old-named container and starts a new one under the derived name. No data is lost since named volumes/networks are referenced by their own names, not the container's name. - Volumes and networks: default name is ALWAYS `<project>_<resource_name>` — Compose hardcodes an underscore joiner between project and resource name for these two resource types specifically, regardless of hyphens used elsewhere (e.g. in the project name or service names). There is no way to get a fully hyphenated *default* volume/network name; omitting `name:` will still produce an underscore between the project prefix and the resource key. To get a fully consistent (zero-underscore) name, you must set the `name:` attribute explicitly to the literal desired string — this bypasses the `<project>_<key>` default entirely and uses the string as-is, unscoped. - Renaming a volume (whether by removing an override and accepting the new derived name, or by setting a new explicit name) changes the actual Docker volume's identity. Docker does NOT migrate data between old and new volume names automatically — the old volume is silently orphaned (not deleted, but no longer attached) and the new name starts empty. Safe migration requires: `docker volume create <new>`, then `docker run --rm -v <old>:/from -v <new>:/to alpine cp -a /from/. /to/` to copy data, THEN cut over the compose file, verify the service works correctly, and only then remove the old volume. Do this with the stack stopped for state that requires consistency (e.g. a live Postgres data directory or an sqlite db with WAL files) — copying while the DB is running risks an inconsistent snapshot. - Networks carry no state, so renaming them (or removing their name: override) is safe with no migration needed — just recreate. - Watch for env vars or external config that reference the OLD literal resource name outside the compose file itself (e.g. a services's config reads a network name from a .env file and passes it to a container-orchestration library like dockerspawner, which calls the Docker API directly using that literal string). Those must be updated in lockstep with any network/volume rename, since they bypass Compose's own service-name-based DNS resolution and address the real Docker resource by name.
docker-composenaming-conventionvolumesnetworkscontainer_namedata-migration
References
- https://docs.docker.com/reference/compose-file/volumes/ — Docker Compose creates a real Docker volume name by prefixing the project name in the form {project_name}_{volume_name} by default; setting the `name` attribute overrides this and the name is used as-is, not scoped with the project/stack name.
- https://docs.docker.com/reference/compose-file/version-and-name/ — The project name used for default resource naming is taken from the top-level `name:` field in the compose file (or the containing directory's basename if unset).