Start with a build and an HTTP check

A Docker image that builds successfully can still contain the wrong files or serve the wrong page. Before adding registry credentials or deployment steps to a Bitbucket pipeline, make the image return something you can check.

Download the complete example, verifier and checklist.

This walkthrough uses one static HTML file and Nginx. We ran the Docker checks locally on 2 October 2026. The Bitbucket configuration is based on Atlassian documentation; we have not run it in a Bitbucket Cloud workspace, pushed an image or deployed an application with it.

The three Docker pieces

The pipeline step image supplies the tools that execute your script. The Docker service supplies the daemon that builds and starts containers. The Dockerfile describes the application image you are building. Changing one does not automatically configure the other two.

Our Dockerfile is deliberately small:

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

The HTML contains the marker bitbucket-docker-smoke-ok. The .dockerignore allows only Dockerfile and index.html into the build context. It keeps unrelated repository files out of this example; add other required application files explicitly when adapting it.

Run the downloadable example locally

Extract the archive, start Docker, open a terminal in the extracted directory and run:

python verify_local.py

The script uses Python's standard library and the installed Docker CLI. It creates a uniquely named image and container, checks the response inside the container and removes those test resources on exit. It does not publish a host port. Downloaded base images and build cache can remain.

Check we executed Result What it establishes Build the supplied Dockerfile PASS The available base image and supplied context can build locally Fetch / and find the expected marker PASS Nginx serves the intended HTML inside the container Fetch /missing Nonzero exit, as expected A missing route is detected Build a Dockerfile copying nonexistent.html Nonzero exit, as expected A missing COPY input causes a build failure

Environment: Docker Desktop 4.81.0, Engine 29.6.1, Linux/amd64 containers on Windows/WSL2. Base image ID: sha256:4a73073bd557c65b759505da037898b61f1be6cbcc3c2c3aeac22d2a470c1752. This is a local image ID, not a registry manifest digest. The download includes the result record. No speed comparison or production reliability claim follows from these four checks.

Put the configuration in Bitbucket

Copy the package's Dockerfile, index.html, .dockerignore and bitbucket-pipelines.yml into a test repository's root, enable Pipelines and commit. Check your build-minute allowance first. The supplied configuration selects Runtime v3, uses docker:27-cli for the CLI and attaches the Docker service to the build step. These settings follow Atlassian's Docker service documentation and Runtime v3 documentation.

The script builds a commit-tagged image, starts it, retries an internal HTTP fetch and checks the marker. A trap removes the container. It stops there: pushing and deployment are separate changes that need their own validation.

The bundled YAML still requires a real hosted run to verify workspace permissions, image downloads and the runner environment. Local success is not proof of hosted success. Both image tags are mutable; pin verified registry digests if you require repeatable base versions.

Diagnose failures in order

  1. If docker version cannot show the server, resolve daemon access before changing the Dockerfile.
  2. If COPY fails, check the build directory and .dockerignore. See Docker's build-context documentation.
  3. If the container stops, inspect docker logs before testing HTTP.
  4. If HTTP succeeds but the marker is absent, check the copied file and URL. A status code alone cannot identify the intended content.
  5. Add registry authentication only after those checks work. Use secured variables and --password-stdin; never put tokens in source files or expose publishing credentials to untrusted pull requests.

Where this helps evaluate a project

This independently authored example is not a reproduction of a customer's system. It helps separate basic build troubleshooting from registry, deployment and application-specific work when scoping a project. It does not establish market size or completed purchases. For other hands-on investigations, visit our research and articles.