Docker / Images and container fundamentals / Lesson 5

Writable layers, bind mounts, and volumes

Place state deliberately and understand why mounted paths can hide image files or change ownership assumptions.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Distinguish ephemeral container writes, host bind mounts, and managed volumes.
Reason about visibility, permissions, backups, and replacement.

Container replacement must not decide data retention

The writable container layer belongs to that container. Replacing the container creates a different layer, so application state stored only there is unsuitable for durable records. A named volume has a separate lifecycle and can be attached to a replacement container. A bind mount points at an explicitly chosen path on the daemon host. Neither mechanism creates a backup, and neither guarantees that concurrent writers use a safe data format.

A volume names managed persistent storage

The Compose fragment below declares a named volume mounted at /data. The current parcel-api fixture does not write there; this configuration teaches placement and ownership for a later stateful extension without pretending data was created. The project-scoped volume name may differ from the logical key. Inspect the actual mount source before discussing retention or recovery, and never delete a volume merely because a container was replaced.

yaml A named data volume in Compose

services:
  api:
    image: parcel-api:lab
    volumes:
      - parcel-state:/data
volumes:
  parcel-state: {}

This is a complete minimal Compose model assuming the earlier lab image already exists. /data is separate from /app/app.py. Volume existence, contents, and ownership are runtime facts; the example makes no claim that a database, backup, or successful write exists. All lifecycle commands remain unexecuted.

A bind mount exposes a host path

Bind mounts suit deliberate local file sharing, such as a read-only development source file. Their host path is interpreted by the daemon, which may be remote from the client. A mount over an existing image path hides the image's original files while mounted. A typo or an unexpected empty directory can therefore make a correct image appear broken. Read-only access limits writes through that mount but does not prove the supplied content is trusted.

yaml A narrow read-only development bind

services:
  api:
    image: parcel-api:lab
    volumes:
      - type: bind
        source: ./app.py
        target: /app/app.py
        read_only: true

The host-side app.py replaces the visible image file at exactly that target. Editing the host file changes the mounted content without rebuilding an image, which is useful in development and undermines immutable-release assumptions in production. Confirm source resolution and regular-file type before using the model.

Permissions follow numeric identity and mapping

The image runs as uid 10001 and gid 10001. A mounted directory must allow that identity, or its mapped host identity under rootless/user-namespace rules, to perform required operations. COPY --chown affects image files, not an already mounted host directory. Do not solve a failed write with world-writable permissions or a privileged container. Identify the correct owner, access mode, security labeling, and approved initialization process instead.

Persistence and recoverability are different

A persistent path can faithfully retain corrupted or accidentally deleted data. Backups need an application-consistent capture method, retention policy, protected storage, and restore verification. Copying live database files without the database's supported procedure can produce an unusable archive. Document which paths are authoritative, which are caches, and which can be regenerated. Keep ownership and version compatibility in the restore plan rather than treating a successful file copy as complete recovery.

Common errors and fixes

Permission denied writing /data.

Why it happens: The runtime uid lacks required access to the mounted path or its security label.
How to fix it: Inspect numeric ownership, mapping, mount mode, and policy before a narrow reviewed correction.
Prevent it next time: Specify data-directory ownership as part of the deployment contract.

Image files disappear after mounting a directory.

Why it happens: The mount obscures existing image content at its target path.
How to fix it: Use the intended narrow target and confirm the source contents.
Prevent it next time: Review every mount against the image filesystem and startup paths.

State disappears after container replacement.

Why it happens: Durable data was written only to the old writable layer.
How to fix it: Recover through the approved incident process and move future state to planned storage.
Prevent it next time: Separate disposable process identity from persistent data ownership.

Check your understanding

1. Will COPY --chown=10001:10001 repair permissions on an existing bind-mounted /data?

Show worked solution

No. COPY modifies image content during the build, while the runtime bind mount supplies different host-backed content over that path. Inspect the mounted source and relevant identity mapping. Any ownership correction belongs to a reviewed storage initialization or administration procedure, not a speculative image rebuild.

2. Which storage fits a source file versus durable generated records?