Images · XB Field Notes

ENTRYPOINT and CMD define defaults that operators can override

Sun, 03 Oct 2027 00:00:00 +0000

An image’s ENTRYPOINT and CMD contribute to the command used when a container is created. With an exec-form ENTRYPOINT, CMD commonly supplies default arguments appended to that entrypoint. Without an entrypoint, CMD can supply the executable and its arguments. These are startup defaults, not an enforcement boundary: an authorized operator can replace the entrypoint or arguments when creating a container.

When it breaks

Trailing arguments in docker run image ... replace CMD; they are not automatically added after CMD’s existing defaults. The exec-form entrypoint remains unless explicitly overridden. A user expecting to append one flag can accidentally discard required defaults, so command-line tools should document which values are optional, which must be repeated, and how their own argument parser treats overrides.

Exec form uses a JSON array and does not implicitly run a shell. A string such as $DEMO reaches the program literally instead of receiving shell variable expansion. Pipes, redirects, and wildcards likewise need an actual interpreter if that is the intended behavior. Shell form changes argument and process semantics, so switching forms is more than a cosmetic syntax choice.

A startup wrapper can also hide the service behind a shell that never forwards the container’s stop signal. Docker normally signals the main container process, waits for the configured timeout, then forces termination if necessary. A service’s correct SIGTERM handler is ineffective if the signal is delivered only to another process that does not pass it on.

Check it quickly

Run this script with host Python and access to a Docker builder after obtaining the pinned base. It was executed with Docker 29.3.1 and Linux arm64 Python 3.11.16. The fixture creates isolated temporary containers with networking disabled, waits for each service’s readiness output, tests stopping, and removes its containers and image tag:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,time,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(name):return json.loads(docker('inspect',name).stdout)[0]

name='xbcatm-entrypoint-'+uuid.uuid4().hex[:10];tag=name+':probe';containers=[name+'-exec',name+'-child']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'args.py').write_text('import json,sys\nprint(json.dumps(sys.argv[1:]))\n')
 (root/'service.py').write_text('import json,os,signal\ndef stop(signum,frame):\n print("stopped",flush=True)\n raise SystemExit(0)\nsignal.signal(signal.SIGTERM,stop)\nprint(json.dumps({"pid":os.getpid()}),flush=True)\nwhile True:signal.pause()\n')
 (root/'exec.sh').write_text('#!/bin/sh\nexec python /service.py "$@"\n')
 (root/'child.sh').write_text('#!/bin/sh\npython /service.py "$@" &\nwait $!\n')
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY args.py service.py exec.sh child.sh /\nRUN chmod +x /exec.sh /child.sh\nENV DEMO=expanded\nENTRYPOINT ["python", "/args.py"]\nCMD ["default", "$DEMO"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert json.loads(docker('run','--rm','--network','none',tag).stdout)==['default','$DEMO']
 assert json.loads(docker('run','--rm','--network','none',tag,'changed').stdout)==['changed']
 assert docker('run','--rm','--network','none','--entrypoint','python',tag,'-c','print("override")').stdout.strip()=='override'
 assert docker('run','--rm','--network','none','--entrypoint','/bin/sh',tag,'-c','printf "%s" "$DEMO"').stdout=='expanded'
 print('CMD supplies literal default arguments; trailing arguments replace it; --entrypoint replaces the executable')
 for container,wrapper in zip(containers,['/exec.sh','/child.sh']):
 docker('run','-d','--name',container,'--network','none','--entrypoint',wrapper,tag)
 deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 logs=docker('logs',container).stdout
 if logs.strip():break
 time.sleep(.05)
 else:raise AssertionError('service did not become ready')
 pid=json.loads(logs.splitlines()[0])['pid']
 assert (pid==1)==(wrapper=='/exec.sh')
 docker('stop','--time','1',container)
 state=inspect(container)['State'];logs=docker('logs',container).stdout
 if wrapper=='/exec.sh':assert state['ExitCode']==0 and 'stopped' in logs
 else:assert state['ExitCode']==137 and 'stopped' not in logs
 print('exec makes the handler PID 1 and stops cleanly; the non-forwarding shell wrapper leaves its child unnotified until forced termination')
finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',tag,check=False)

The first image command prints its received argument list. With no override it receives default and the literal $DEMO, even though the image defines DEMO as expanded. Supplying changed after the image name replaces both default arguments, and the program receives exactly one argument. These assertions inspect the final argument vector rather than guessing from Dockerfile syntax.

Using --entrypoint python and explicit Python arguments runs an entirely different command that prints override. Using /bin/sh -c explicitly expands $DEMO and prints expanded. Together, these cases show both that ENTRYPOINT is overridable and that expansion belongs to the invoked shell, not to a hidden expansion step in exec-form command construction.

The second part compares two wrapper scripts launching the same service. The exec wrapper replaces itself with Python, which reports PID 1 inside the container. Its installed SIGTERM handler prints stopped and exits with status zero when Docker stops the container. The fixture verifies the message and the recorded exit status.

The other wrapper starts Python as a child and waits, without forwarding signals. The service reports a PID other than one. Stopping that container with a one-second timeout produces exit status 137 in the recorded environment, and the service never prints stopped. The forced termination is observed directly; no conclusion is inferred merely from the presence of a shell script.

PID 1 has special signal and child-reaping responsibilities in a Linux PID namespace. An exec wrapper makes the service the signal recipient, but it does not automatically implement application cleanup, drain in-flight work, or reap arbitrary descendants. The service still needs appropriate behavior, or a deliberately chosen init/supervision arrangement when its process model requires one.

Treat startup and shutdown as one interface

Use valid JSON arrays with double-quoted strings for exec-form instructions. Keep the executable and stable arguments clear, and document how callers replace defaults. If initialization requires a shell wrapper, finish with an appropriate exec when the wrapper’s job is to hand control to one foreground service. Quote forwarded arguments so their boundaries remain intact.

Test the actual deployed launch path, including any orchestration overrides. A correct image entrypoint can be replaced by a configuration that introduces another shell, and an overridden command may omit necessary initialization. Inspect the resulting process tree and exercise termination with representative active work.

Choose the stop signal and grace period according to the service’s contract. Record readiness, successful cleanup, and exit status separately. A container that eventually disappears after SIGKILL has stopped, but that observation alone does not prove requests completed or buffered state was safely handled.

Sources

Dockerfile ENTRYPOINT and CMD, exec and shell forms, argument combination, and entrypoint overrides, checked 2026-09-12.
Docker container stop, stop signals, timeout, and forced termination, checked 2026-09-12.
pid_namespaces(7), namespace-init signal behavior and termination of namespace members, checked 2026-09-12.

Image tags can move while existing containers keep their image

Tue, 24 Aug 2027 00:00:00 +0000

An image tag is a readable name associated with an image reference. Unless a registry policy prevents reassignment, the same tag can later identify another artifact. Tags such as v1.4 and latest differ in naming convention, not in an inherent guarantee of immutability. Reproducing a deployment requires recording the artifact actually selected, together with the platform and runtime configuration that determined its behavior.

When it breaks

The word latest does not ask a registry to find its newest image or highest semantic version. It is the conventional default tag when a reference omits one. Publishing or tagging another version does not automatically move latest; someone or some automation must update that specific reference. Treating every push as an implicit latest update gives an incorrect picture of release behavior.

A tag’s local resolution can also differ from its current registry resolution. Pull policy, local image availability, and orchestration behavior determine when the registry is consulted. Two machines running a readable tag can therefore use different artifacts. Recording only the command text leaves uncertainty about what each machine actually fetched and which cached reference it retained.

Moving a tag does not rewrite the image selected by an already-created container. Restarting that container retains its configured image and writable state rather than recreating it from the tag’s new target. An update procedure that retags an image and merely restarts existing containers can therefore appear successful while continuing to run the old application.

Check it quickly

Run this Python script with a Docker builder and the pinned base available. The recorded environment used Docker 29.3.1 on Linux arm64. All tags are unique local names; nothing is pushed to a registry. Containers use no network, and cleanup removes only the experiment’s container and tags:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(name,kind='image'):return json.loads(docker(kind,'inspect',name).stdout)[0]

name='xbcatm-tags-'+uuid.uuid4().hex[:10];tags=[name+':one',name+':two',name+':release',name+':latest'];container=name+'-old'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY version.txt /version.txt\nCMD ["cat", "/version.txt"]\n')
 for tag,version in zip(tags,['one','two']):
 (root/'version.txt').write_text(version+'\n');docker('build','--network','none','-t',tag,str(root))
 one=inspect(tags[0])['Id'];two=inspect(tags[1])['Id'];assert one!=two
 docker('image','tag',tags[0],tags[2]);docker('image','tag',tags[0],name)
 assert inspect(tags[2])['Id']==inspect(tags[3])['Id']==one
 docker('create','--name',container,'--network','none',tags[2])
 docker('image','tag',tags[1],tags[2])
 assert inspect(tags[2])['Id']==two and inspect(tags[3])['Id']==one
 assert inspect(container,'container')['Image']==one
 assert docker('start','--attach',container).stdout.strip()=='one'
 assert docker('run','--rm','--network','none',tags[2]).stdout.strip()=='two'
 assert docker('run','--rm','--network','none',tags[3]).stdout.strip()=='one'
 print('moving release changes newly created containers; the existing container still runs its original image')
 print('omitting a tag selected latest, but updating release did not update latest')
 docker('image','rm',tags[2]);assert inspect(tags[1])['Id']==two
 print('removing one tag leaves another reference to the same image intact; all operations stayed local')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

The script builds two images whose /version.txt contents are one and two. Their image identities differ. It points a release tag at the first image and tags that same image using a repository name with no explicit tag. Inspection confirms that the omitted tag became latest, and both references initially select the first image.

Before moving release, the script creates a container from it without starting the container. It then moves release to the second image. The release tag now identifies the second artifact, while latest still identifies the first. This isolates tag reassignment from the independent default-tag convention and demonstrates that related names do not automatically move together.

Starting the existing container prints one. Creating a new container from release prints two, while creating one from latest prints one. The container inspection also retains the original selected image identity. These assertions compare actual execution results, so the distinction does not depend solely on interpreting a table of tag names.

Removing the release tag leaves the second image available through its two tag. A tag is a reference, and removing one reference does not necessarily delete shared content or every other name. Image reclamation depends on remaining references and the engine’s storage rules; this experiment does not prune caches or measure physical space recovery.

The fixture compares identities returned by the current engine without assuming that every inspect Id universally means an OCI configuration digest. Modern image stores can expose different object levels. Registry indexes, platform manifests, image configurations, and layer blobs each have their own digests, so the object type and reference context must accompany an identity claim.

Promote the artifact that was tested

For registry deployments, record a repository-qualified digest reference from the publication workflow. A digest can identify an image index containing multiple platform-specific manifests; selecting the intended platform still matters. Retain the corresponding artifact and required blobs so a later rollback can actually retrieve them. A recorded hash cannot recover content that is no longer available.

Use tags as human navigation when useful, and enforce registry immutability rules if the release process promises that version tags never move. Verify the policy rather than inferring it from a version-shaped name. Digest pinning also does not prove who built an artifact or whether it is safe; provenance and behavioral validation answer those questions.

After deployment, compare the running workload’s selected artifact and expected behavior with the release record. An updated tag, a successful pull, and a running container are separate observations. The release is established by connecting them to the exact artifact that passed validation.

Sources

Docker image tag, local tag creation and the default latest tag, checked 2026-09-12.
Docker image pull, pulling repository artifacts by tag or digest, checked 2026-09-12.
OCI image index 1.1.1, an index referencing platform-specific image manifests, checked 2026-09-12.
OCI image manifest 1.1.1, manifest references to configuration and layer objects, checked 2026-09-12.

Deleting a file in a later image layer does not erase its bytes

Mon, 16 Aug 2027 00:00:00 +0000

Container image layers describe filesystem changes applied in order. A layer can add or replace a file, or record that an earlier path should disappear from the merged filesystem. That final view is what a normal container process sees, but it is not the complete history of bytes distributed with the image. Inspecting only the running container can therefore miss data retained in earlier layers.

When it breaks

Copying a credential into an image and deleting it in a later RUN does not remove the credential from the earlier immutable layer. Anyone who can obtain the relevant layer may recover the original bytes. The same mechanism explains why deleting a large build archive in a later instruction can leave the image’s distributed content unnecessarily large even though the final path is absent.

Layer changes are filesystem changesets, not necessarily compact binary differences. Replacing a large file can place its replacement content in another layer. Deletion uses a whiteout marker to suppress an earlier path when layers are applied. OCI also defines opaque-directory behavior for hiding lower directory contents, so implementing layer application as ordinary repeated tar extraction is insufficient.

Not every Dockerfile instruction creates a filesystem layer. ENV, LABEL, and CMD change image configuration and can add history entries marked empty_layer. Counting Dockerfile lines or history records therefore does not reliably count root filesystem layers. Configuration changes still matter to execution and artifact identity even when they add no application file bytes.

Check it quickly

Use Python with access to a Docker builder and the pinned base digest. The recorded run used Docker 29.3.1 with its containerd image store and a Linux arm64 Python 3.11.16 base. The marker is deliberately public. The script builds and saves one temporary image, inspects archive members without extracting them into the host filesystem, and removes its own tag:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,tarfile,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(["docker",*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker("image","inspect",image).stdout)[0]

name='xbcatm-whiteout-'+uuid.uuid4().hex[:10];tag=name+':probe';marker=b'PUBLIC_DEMONSTRATION_BYTES\n'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'original.txt').write_bytes(marker)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY original.txt /demo/original.txt\nRUN rm /demo/original.txt\nENV EXAMPLE_MODE=demo\nLABEL example.purpose="public fixture"\nCMD ["python", "-c", "from pathlib import Path;assert not Path(\'/demo/original.txt\').exists();print(\'absent\')"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert docker('run','--rm','--network','none',tag).stdout.strip()=='absent'
 archive=root/'image.tar';docker('image','save','-o',str(archive),tag)
 with tarfile.open(archive) as outer:
 manifests=json.load(outer.extractfile('manifest.json'));assert len(manifests)==1
 manifest=manifests[0];config=json.load(outer.extractfile(manifest['Config']))
 assert len(manifest['Layers'])==len(config['rootfs']['diff_ids'])
 assert len(manifest['Layers'])==len(inspect(BASE)['RootFS']['Layers'])+2
 found_data=False;found_whiteout=False
 for layer in manifest['Layers'][-2:]:
 with tarfile.open(fileobj=outer.extractfile(layer),mode='r:*') as contents:
 for entry in contents:
 path=entry.name.removeprefix('./')
 if path=='demo/original.txt':found_data=contents.extractfile(entry).read()==marker
 if path=='demo/.wh.original.txt':found_whiteout=True
 assert found_data and found_whiteout
 assert all(item.get('empty_layer') for item in config['history'][-3:])
 print('the final container hides the removed file, but the older layer still contains the exact public marker')
 print('the deletion layer contains a whiteout; ENV, LABEL and CMD add metadata history without filesystem layers')
finally:docker('image','rm',tag,check=False)

The Dockerfile copies original.txt into /demo, then removes it in a later RUN. The configured container command asserts the path is absent and prints absent. That confirms the merged runtime view. It does not establish that the bytes are absent from the image archive, so the next part examines the saved representation separately.

The archive’s manifest.json identifies its configuration and ordered layer files. The script reads the configuration’s rootfs.diff_ids and checks that the number of filesystem layers matches the manifest. It then inspects the final two layer archives, which correspond to the COPY addition and the subsequent deletion in this particular build.

The addition layer still contains the exact PUBLIC_DEMONSTRATION_BYTES marker. The deletion layer contains demo/.wh.original.txt. That whiteout instructs layer application to hide the lower file; it does not edit the original layer in place. Both facts are asserted directly, so an absent file in the container cannot be mistaken for evidence of secure erasure.

The final three configuration-history entries describe ENV, LABEL, and CMD and are marked as having no filesystem layer. The image has two additional filesystem layers above its base, not five. This is a concrete counterexample to the claim that each Dockerfile instruction necessarily appends another filesystem diff.

Archive representation and runtime storage are different interfaces. The experiment inspects the image-save format produced by the recorded Docker version and OCI changeset semantics. It does not assume that a snapshotter must store its internal deletion markers as the same visible .wh. filenames, nor does it measure how a particular host allocates physical blocks.

Exclude unnecessary bytes before they enter an image

Use an appropriate build context and ignore rules to keep unrelated files out of COPY inputs. Pass build credentials through the builder’s secret mechanism, and ensure commands do not write those credentials into retained outputs. If a real credential entered a published layer, rotate it and handle retained copies; a later deletion layer is not remediation.

Create and remove disposable package indexes or temporary archives within the same build operation when they are needed only during that operation. A separate final stage can copy the required runtime artifacts without inheriting the builder’s filesystem layers. Still inspect exported caches and copied outputs, because earlier build material can remain in the builder or escape through another export.

Judge the result by the actual final artifact and its intended runtime dependencies. Fewer layers alone does not guarantee smaller downloads, faster starts, or safer content. The useful question is which bytes are distributed, which paths become visible, and whether every retained file has a justified role.

Sources

OCI filesystem layer changesets 1.1.1, file additions, modifications, removals, and whiteout application, checked 2026-09-12.
OCI image configuration 1.1.1, rootfs DiffIDs and history entries without filesystem layers, checked 2026-09-12.
Dockerfile reference, COPY, RUN, ENV, LABEL, and CMD behavior, checked 2026-09-12.

Related images share layers; running containers keep separate changes

Mon, 22 Mar 2027 00:00:00 +0000

An image describes an ordered filesystem assembled from immutable layer changesets, together with configuration such as its default command. Related images can reference the same base layers while adding different application files. A running container gets its own writable layer above that image. Distinguishing those three things explains how image reuse saves work without making every container’s runtime edits visible to its neighbors.

When it breaks

Summing the displayed sizes of several related images can overstate their combined local storage use because shared content may be counted repeatedly. Transfer size, unpacked filesystem size, and actual storage allocated by a snapshotter are also different measurements. Layer sharing supports reuse, but it does not justify claiming an exact disk saving without measuring the relevant storage implementation and accounting method.

The opposite mistake is treating container changes as edits to the image. Installing a package or changing a file inside one ordinary container modifies that container’s writable filesystem state. A new container from the original image does not automatically inherit the repair. An operator who patches a running service and then replaces it can therefore see the original failure return.

Sharing does not make an image layer a universal application compatibility boundary. Two applications might use equal base layers yet depend on different configuration, mounted data, architectures, or library versions introduced later. Compare the ordered filesystem identifiers and the actual behavior under test; a matching readable image tag alone says little about which bytes or settings are in use.

Check it quickly

Run this script with Python and a Docker builder after obtaining the pinned Python base digest. The recorded environment used Docker 29.3.1 on Linux arm64, with Python 3.11.16 inside the image. It creates two related images and two temporary containers, uses no container networking, and removes only its own named containers and tags when finished:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(["docker",*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker("image","inspect",image).stdout)[0]

name='xbcatm-layers-'+uuid.uuid4().hex[:10];tags=[name+':left',name+':right'];containers=[name+'-one',name+'-two']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'shared.py').write_text('value=10\n# '+name+'\n')
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY shared.py /app/shared.py\nCOPY main.py /app/main.py\nCMD ["python", "/app/main.py"]\n')
 for tag,increment in zip(tags,[1,2]):
 (root/'main.py').write_text(f'from shared import value\nprint(value+{increment})\n')
 docker('build','--network','none','-t',tag,str(root))
 left=inspect(tags[0])['RootFS']['Layers'];right=inspect(tags[1])['RootFS']['Layers']
 assert left[:-1]==right[:-1] and left[-1]!=right[-1]
 assert docker('run','--rm','--network','none',tags[0]).stdout.strip()=='11'
 assert docker('run','--rm','--network','none',tags[1]).stdout.strip()=='12'
 print('two images share',len(left)-1,'filesystem layer identities and differ in the final application layer')
 for container in containers:
 docker('run','-d','--name',container,'--network','none',tags[0],'python','-c','import time;time.sleep(60)')
 docker('exec',containers[0],'python','-c',"from pathlib import Path;Path('/app/shared.py').write_text('value=100\\n')")
 assert docker('exec',containers[0],'python','/app/main.py').stdout.strip()=='101'
 assert docker('exec',containers[1],'python','/app/main.py').stdout.strip()=='11'
 assert '/app/shared.py' in docker('diff',containers[0]).stdout
 assert inspect(tags[0])['RootFS']['Layers']==left
 assert docker('run','--rm','--network','none',tags[0]).stdout.strip()=='11'
 print('a write in one container changes its writable layer while the sibling container and original image retain the old code')
finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False)

Both builds copy the same shared.py, which defines a value of ten. Their final main.py differs: one adds one and the other adds two. The resulting programs print 11 and 12. Image inspection shows an identical ordered prefix of five filesystem layers and a different final application layer in this recorded base and build arrangement.

The five-layer count is an observation, not a requirement for every Python image. The meaningful assertion compares all layers before the final COPY and confirms that the last identifiers differ. If the publisher changes the base structure, a new digest may have another number of layers while the same sharing principle continues to apply.

Next, two long-running containers start from the first image. A command changes /app/shared.py in only the first container to define one hundred. Executing its application now prints 101. Executing the sibling’s application still prints 11, and docker diff reports the changed path in the edited container’s writable state.

The original image retains its layer identifiers. A fresh container created from that image also prints 11, proving that the runtime edit was not written back into the image. The experiment uses ordinary image-backed paths with no shared volume or host bind mount. A shared writable mount would have a different visibility contract and must be examined separately.

The inspected RootFS.Layers list identifies uncompressed filesystem changesets through DiffIDs. Those values should not be casually substituted for registry manifest digests, compressed layer-blob digests, or image configuration digests. All are content identifiers, but they identify different serialized objects and serve different purposes in storage, retrieval, and artifact selection.

Build and replace the intended artifact

Keep common dependency inputs stable when related applications can actually share them, then copy application-specific code later. This improves the opportunity for cache and content reuse without requiring that unrelated applications use an artificial common dependency set. Correct dependency boundaries come from the software, not from maximizing the number of matching hash strings.

Turn a necessary runtime repair into a reviewed image change and test a replacement container. Persist durable application data through an explicit storage contract; do not rely on the writable layer surviving replacement. Conversely, do not assume deleting one container removes data held in an independently managed volume.

For operational accounting, measure shared and unique storage with tools appropriate to the builder and image store. For release identity, record the artifact reference and runtime configuration. For debugging, inspect both the image and container differences. These observations answer related questions, but no single image-size column or tag answers all of them.

Sources

Docker image layers, shared read-only layers and container writable layers, checked 2026-09-12.
OCI image configuration 1.1.1, ordered filesystem DiffIDs and their distinction from other digests, checked 2026-09-12.
Optimize Docker cache usage, dependency ordering and narrow build inputs, checked 2026-09-12.

Lazy loading defers what is not needed yet

Wed, 14 Oct 2026 00:00:00 +0000

Lazy loading postpones work until it becomes useful. For an HTML image, loading="lazy" lets the browser defer its request until the image is near the viewport according to the browser’s policy. This can reduce initial transfers on long articles, but the attribute is a scheduling input, not a guarantee that every unseen image remains undownloaded.

Let the browser schedule ordinary images

Native lazy loading uses the real src or srcset, so ordinary image markup remains understandable without a custom scroll handler. The browser chooses its loading distance and may adapt that decision to implementation and connection conditions. Authors do not set a native distance threshold through the loading attribute. An IntersectionObserver implementation has different controls and additional application responsibility; it is not required merely to use native loading.

Keep images needed for the first view eager, especially an important hero image. Deferring an image that determines the largest visible content can delay useful rendering. Conversely, preloading a deliberately deferred image can undermine the intended transfer saving. Decide from the image’s role and measured behavior rather than assigning the same loading policy to every asset on the page.

Specify intrinsic width and height so the browser can reserve an aspect ratio before bytes arrive. Responsive CSS can still reduce the rendered width and maintain height automatically. Without useful dimensions, images may occupy little or no space before loading, change which content appears near the viewport, and move text when they arrive. Correct alt text also matters when an image cannot be displayed.

When it breaks

Testing only the initial load event can miss deferred images. The page may finish its load event while a distant lazy image has not completed. Inspect individual image completion, natural dimensions, requests, and actual rendering after scrolling. A request failure and a request deliberately not started are different states, even if both initially show no decoded pixels.

A page with no custom JavaScript can use native lazy loading, but MDN documents that deferral requires scripting to be enabled in the browser as an anti-tracking measure. Disabling JavaScript is therefore not equivalent to merely removing application scripts. Validate the environments your site supports and avoid claiming identical request savings in every configuration.

The attribute applies to supported elements, not arbitrary CSS background images. Likewise, content-visibility can skip rendering work without promising that all associated network requests are deferred. For fast scrolling on a slow connection, native loading can still reveal a placeholder before the image arrives. Inspect visible gaps and layout stability, not just a smaller initial request count.

Check it quickly

Save the following as lazy-images.py and run python3 lazy-images.py. The Python 3 command verifies that the local page and both images are available. Its output explicitly reports native_loading_tested_by_cli false, because an HTTP client fetching markup does not execute a browser’s image scheduler.

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Event, Lock, Thread
import json
import sys

requests = []
lock = Lock()
page = '''<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Native image loading</title><link rel="icon" href="data:,"><style>body{font:18px sans-serif;margin:24px;max-width:700px}img{max-width:100%;height:auto}.gap{height:60000px}</style></head><body><h1>Native image loading</h1><p>The first image loads eagerly. Scroll down to reach the reserved lazy image.</p><img id="first" src="/eager.svg" width="480" height="160" alt="Eager example"><div class="gap"></div><h2>Deferred image</h2><img id="late" src="/late.svg" loading="lazy" width="480" height="160" alt="Lazy example"><p>Both image dimensions were reserved before loading.</p></body></html>'''


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 if self.path == '/':
 data, kind = page.encode(), 'text/html; charset=utf-8'
 elif self.path in ('/eager.svg', '/late.svg'):
 with lock:
 requests.append(self.path)
 color = '#2563eb' if self.path == '/eager.svg' else '#047857'
 label = 'EAGER' if self.path == '/eager.svg' else 'LAZY'
 data = f'<svg xmlns="http://www.w3.org/2000/svg" width="480" height="160"><rect width="480" height="160" fill="{color}"/><text x="24" y="92" font-family="sans-serif" font-size="36" fill="white">{label}</text></svg>'.encode()
 kind = 'image/svg+xml'
 elif self.path == '/events':
 with lock:
 data = json.dumps(requests).encode()
 kind = 'application/json'
 else:
 self.send_error(404)
 return
 self.send_response(200)
 self.send_header('Content-Type', kind)
 self.send_header('Cache-Control', 'no-store')
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 if '--serve' in sys.argv:
 print(json.dumps({'origin': f'http://127.0.0.1:{server.server_port}'}), flush=True)
 try:
 Event().wait()
 except KeyboardInterrupt:
 pass
 else:
 for path in ('/', '/eager.svg', '/late.svg'):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 data = response.read()
 assert response.status == 200
 if path == '/':
 assert b'loading="lazy"' in data and b'height:60000px' in data
 finally:
 connection.close()
 print(json.dumps({'page_and_assets_available': True, 'native_loading_tested_by_cli': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

Next run python3 lazy-images.py --serve and open the printed origin in a fresh browser profile with scripting enabled. The page itself contains no JavaScript. It places an eager image near the heading and a lazy image after a deliberately exaggerated 60,000-pixel gap. Inspect /events before scrolling, then scroll to the Deferred image heading and inspect again. Stop the server with Ctrl-C.

In Chrome 152.0.7977.83, both a 1440×1000 desktop viewport and a 390×844 mobile viewport initially requested only eager.svg. The distant image had naturalWidth zero while reserving 480×160 and 342×114 rendered space respectively. After scrolling, late.svg was requested once, naturalWidth became 480, and the reserved sizes stayed unchanged. The large gap makes this a scheduling demonstration, not a realistic page layout or performance benchmark. No disabled-scripting case was measured. Repeat the scroll check under your actual layouts and connection conditions before attributing a user-visible improvement to the attribute.

Sources

MDN: Lazy loading, deferring non-critical resources and loading mechanisms, checked 2026-09-13.
MDN: The Image Embed element, loading behavior, dimensions and scripting requirements, checked 2026-09-13.

Multi-stage builds need a tested runtime boundary

Fri, 25 Sep 2026 00:00:00 +0000

A multistage Dockerfile can compile software in one stage and copy selected outputs into another stage that becomes the runtime image. The final stage inherits its own base and the files explicitly copied into it, rather than automatically inheriting the builder’s compiler, source tree, and package caches. This creates a useful boundary, but the author must still identify everything the program needs when it executes.

When it breaks

COPY can successfully place a dynamically linked executable into a scratch image even when its ELF interpreter and shared libraries are missing. The image build may finish normally because copying does not execute the program or validate its entire runtime dependency graph. Startup can then report no such file or directory despite the executable itself being present at the configured path.

Scripts need their interpreters, applications may need certificate roots or timezone data, and programs can load plugins or assets only on particular request paths. A simple launch test might miss those later requirements. Selecting a small runtime base is useful only when it provides the actual contract the application relies on, including supported architecture and necessary filesystem paths.

The earlier stage is also not securely erased just because it is absent from the final image’s ancestry. Builder caches and explicitly exported intermediate images can retain its contents. Sensitive build inputs require appropriate secret handling, and copied outputs must be checked for accidental inclusion. Multistage structure controls final filesystem composition; it is not an automatic confidentiality guarantee.

Check it quickly

Run this script with Python, Docker, the pinned Python base, and network access for the builder’s Debian package installation. Runtime containers disable networking. The recorded run used Docker 29.3.1 on Linux arm64 and GCC 12.2.0 from Debian’s 12.2.0-14+deb12u1 package. The package repository is live, so the exercise demonstrates runtime composition rather than promising identical compiler bytes forever:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,tarfile,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=360)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker('image','inspect',image).stdout)[0]

name='xbcatm-stages-'+uuid.uuid4().hex[:10];tags=[name+':builder',name+':good',name+':bad'];container=name+'-inspect'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'square.c').write_text('#include <stdio.h>\n#include <stdlib.h>\n#include <errno.h>\nint main(int argc,char **argv){\n char *end;long value;\n if(argc!=2){fprintf(stderr,"one integer required\\n");return 2;}\n errno=0;value=strtol(argv[1],&end,10);\n if(errno||end==argv[1]||*end||value<0||value>100){fprintf(stderr,"range 0..100\\n");return 2;}\n printf("%ld\\n",value*value);return 0;\n}\n')
 (root/'Dockerfile').write_text(f'''FROM {BASE} AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc libc6-dev && rm -rf /var/lib/apt/lists/*
WORKDIR /source
COPY square.c .
RUN gcc -O2 -Wall -Wextra -Werror -static -o /square-static square.c && gcc -O2 -Wall -Wextra -Werror -o /square-dynamic square.c
FROM scratch AS good
COPY --from=builder /square-static /square
USER 65532:65532
ENTRYPOINT ["/square"]
FROM scratch AS bad
COPY --from=builder /square-dynamic /square
USER 65532:65532
ENTRYPOINT ["/square"]
''')
 for tag,target in zip(tags,['builder','good','bad']):docker('build','--target',target,'-t',tag,str(root))
 print('compiler:',docker('run','--rm','--network','none',tags[0],'gcc','--version').stdout.splitlines()[0])
 for argument,expected in [('0','0'),('7','49'),('100','10000')]:
 assert docker('run','--rm','--network','none',tags[1],argument).stdout.strip()==expected
 for argument in ['7x','-1','101','','999999999999999999999999999']:
 invalid=docker('run','--rm','--network','none',tags[1],argument,check=False)
 assert invalid.returncode==2 and 'range 0..100' in invalid.stderr
 invalid=docker('run','--rm','--network','none',tags[1],check=False)
 assert invalid.returncode==2 and 'one integer required' in invalid.stderr
 invalid=docker('run','--rm','--network','none',tags[1],'7','8',check=False)
 assert invalid.returncode==2 and 'one integer required' in invalid.stderr
 good=inspect(tags[1]);builder=inspect(tags[0]);assert good['Size']<builder['Size'] and len(good['RootFS']['Layers'])==1
 assert good['Config']['User']=='65532:65532'
 docker('create','--name',container,tags[1],'7');archive=root/'rootfs.tar';docker('export','-o',str(archive),container)
 with tarfile.open(archive) as contents:
 names={entry.name.removeprefix('./') for entry in contents}
 assert 'square' in names and 'usr/bin/gcc' not in names and 'source/square.c' not in names
 bad=docker('run','--rm','--network','none',tags[2],'7',check=False)
 assert bad.returncode!=0 and 'no such file or directory' in bad.stderr
 print('the static final image runs valid input, rejects invalid input, and contains one application layer without compiler or source')
 print('recorded image sizes:',builder['Size'],'builder bytes;',good['Size'],'final bytes')
 print('the dynamic scratch image builds successfully but cannot start because its interpreter/runtime was not copied')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

The builder compiles the same small C program twice, once statically and once dynamically. The program accepts one integer in the range zero through one hundred and prints its square. Compilation enables warnings and treats them as errors. Named final targets copy only the corresponding executable into scratch and select numeric user and group 65532.

The static final image prints 0, 49, and 10000 for inputs zero, seven, and one hundred. It returns status two for trailing text, negative or out-of-range values, an empty argument, and an integer too large for strtol. Missing or extra arguments also return status two. These checks exercise valid boundaries and rejected inputs in the actual final image.

Inspection confirms one filesystem layer in that final image and the intended nonroot numeric user. Exporting a created container shows /square, with no compiler or source file at the builder’s paths. The export is inspected as an archive; it is not extracted over the host filesystem. This verifies final composition independently of whether the Dockerfile merely looks minimal.

Docker reported 109,490,331 bytes for the builder image and 312,508 bytes for the static final image in the recorded run. These are the engine’s image-size fields, not a measurement of unique physical disk allocation or network transfer time. The useful invariant is that the final image excludes the toolchain and is smaller under the same reported accounting method.

The dynamic final target also builds successfully, but starting it fails with a missing-file error because its interpreter/runtime was not copied. This is the critical negative test. The failure is expected and asserted; it disproves the idea that a successful final COPY automatically tells the builder which runtime libraries should be added.

Validate what the last stage actually runs

Choose an appropriate runtime image for the application. Static linking fits this small calculation, but does not prove that every statically linked service needs no external files or runtime-loaded components. For a dynamic application, supply compatible runtime libraries or a suitable runtime base and execute representative functionality inside the final artifact.

Use named stages and narrow COPY paths so reviewers can see the handoff. Avoid copying a broad builder directory that silently includes tests, credentials, caches, or unused tools. Set working directories, writable paths, user identity, and startup arguments according to the runtime’s real requirements.

Test the final stage after dependency or compiler updates, including errors and less common paths that load extra resources. Keep the selected artifact identity with the results. A smaller image is a useful outcome when it still fulfills the service contract; build success alone cannot establish that contract.

Sources

Docker multi-stage builds, named stages, target selection, and copying selected artifacts, checked 2026-09-12.
Dockerfile reference, COPY –from, scratch, USER, and exec-form entrypoints, checked 2026-09-12.
execve(2), missing executable interpreters and execution errors, checked 2026-09-12.