To create a Docker image, place a plain-text Dockerfile in your application directory, describe the runtime and startup command, then run docker build with that directory as the build context. For example: docker build -t my-image:1.0 .. After the build completes, start a container from the image with docker run --rm my-image:1.0.
The image is the build output; the container is a running instance created from that image. Publishing the image to a registry is optional and is a separate step from building and running it.
As an Amazon Associate I earn from qualifying purchases.
What you create: an image and a container
A Docker image is the packaged result of processing a Dockerfile. It contains the filesystem layers and metadata needed to start your application. A container is a running (or stopped) instance created from that image. Building produces the image; running starts a container from it. Docker presents building, tagging, running, and publishing as distinct parts of the workflow.
This distinction explains a common beginner experience: a successful docker build does not start your program. You must run the resulting image separately with docker run.
#1 Best Overall
Docker’s official overview of this workflow is available in Build, tag, and publish an image.
What you need before building
- A working Docker installation with the Docker CLI available in your terminal.
- An application directory containing the source files and dependency files your image must copy.
- A terminal opened in that directory, or a deliberate choice of another build-context path.
- A plain-text file named
Dockerfileunless you plan to pass a different filename explicitly.
The instructions in a Dockerfile are application-specific. A Node project, Python service, compiled program, and static site normally need different base images, dependency commands, and startup commands. The example below is intentionally narrow so every line has a clear meaning.
A small, application-specific Dockerfile
Assume the directory contains a compatible Node application with a package.json, a suitable lockfile if the project uses one, and a start script that launches the application. Save this as a file named Dockerfile in the project directory:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "start"]This is an illustrative teaching example, not a universal recipe or a claim that this particular Node base-image variant is right for every project. Verify the runtime version, base-image variant, package manager, and start command against the application you are actually containerizing.
What each instruction does
| Instruction | Purpose in this example |
|---|---|
FROM node:22-alpine |
Selects the starting image and establishes the runtime environment. The FROM instruction is where a build gets its base image. |
WORKDIR /app |
Sets /app as the working directory for subsequent instructions and for the default command. |
COPY package*.json ./ |
Copies the package manifests from the build context into /app. The dependency step needs these files. |
RUN npm install |
Executes the dependency-install command while the image is being built. |
COPY . . |
Copies the rest of the files available in the build context into the working directory. |
CMD ["npm", "start"] |
Defines the default command Docker uses when a container starts from this image. |
If your project uses another package manager, has no start script, or needs a compilation step, change the dependency and startup instructions. A Dockerfile is a set of build instructions, not a guarantee that any application can use the same sequence unchanged.
Decide what the file must provide
Before writing instructions, identify three application facts: which runtime version the program requires, which files describe its dependencies, and which command starts it. Those choices determine the FROM, COPY, dependency-install, and CMD lines. If any required file is outside the context you plan to pass to Docker, reorganize the command or choose a higher-level context that contains it.
Keep the example’s assumptions visible to anyone who reuses it. It expects a Node project and a start script; it does not promise to compile a project, expose a network port, or select a production-only dependency mode. Those behaviors belong in instructions designed for that particular application.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Build context: what the final dot means
In docker build ., the final period is not punctuation. It is the path supplied as the build context, and it means “use the current directory.” The builder can use files in that context when a Dockerfile refers to them with instructions such as COPY.
Run the command from the directory that contains the Dockerfile and the application files it needs:
cd path/to/your-app
docker build -t my-image:1.0 .If you run the command from a parent directory, the context becomes that parent directory. If you run it from an unrelated directory, the Dockerfile may not be found or the files named by COPY may not be available. Conversely, a file located outside the context cannot simply be copied into the image by referring to a path above the context directory. The context path or URL is a deliberate boundary for the build.
A context can be a path or a URL, not only a local dot. The important question is always the same: does the selected context contain every file that the Dockerfile names? The Dockerfile may be selected separately, but changing its filename does not silently enlarge or move the context.
Docker’s context documentation explains this behavior in Build context. The official build guide also uses the current directory as the basic context in its beginner workflow.
Build and tag the image
From the application directory, run:
docker build -t my-image:1.0 .The -t (or --tag) option gives the result a memorable image reference. In this example, my-image is the repository name and 1.0 is the tag. An image reference can include a registry and namespace using the form [HOST[:PORT_NUMBER]/]PATH[:TAG]. If you omit the tag, Docker uses latest; an explicit tag such as 1.0 makes the example’s intended version clear.
The build process reads the Dockerfile, sends the selected context to the builder, executes each instruction, and creates the image named by -t. Docker describes BuildKit this way: “BuildKit is the build engine that solves the build steps in a Dockerfile to produce a container image or other artifacts.” See Docker builders for the official description.
Understand the image reference
The name you choose is the same reference you use when starting the container. In my-image:1.0, the portion before the colon identifies the image path and the portion after it identifies the tag. A registry-qualified reference adds a host and, commonly, a namespace, such as registry.example.com/team/my-image:1.0. This naming convention lets a local build and a later registry workflow use an explicit destination without changing the application instructions.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsLeaving off the tag is valid, but Docker then assigns latest. That label is a default, not proof that the image is the newest build. For a tutorial, release, or handoff, an explicit tag makes it easier to run the exact reference you intended.
When the Dockerfile has another name
The default filename is Dockerfile. If you intentionally use another file, select it with the file option supported by the build command. For example:
docker buildx build --file Dockerfile.dev -t my-image:1.0 .The context is still the final argument, so the dot continues to mean the current directory. The --file option changes which Dockerfile is read; it does not automatically change the context.
Follow the first-build workflow
- Open the project directory. Confirm that the source files and dependency manifests needed by the Dockerfile are inside this directory or one of its subdirectories.
- Create the Dockerfile. Use the application-appropriate base image, working directory, copy instructions, dependency command, and startup command.
- Check the context. In the basic command, the final
.must point to the directory containing the files referenced byCOPY. - Build and tag. Run
docker build -t my-image:1.0 .and wait for the command to finish successfully. - Start a container. Run
docker run --rm my-image:1.0. Docker creates a container from the image and uses the image’s default command.
The exact application behavior after step five depends on the command in CMD. A service may continue running, while a one-shot command may finish and exit normally.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →A quick preflight checklist
Use this short check before spending time interpreting a build error:
- Is the file spelled exactly
Dockerfile, or did you supply the alternate filename explicitly? - Does the final argument point to the directory containing every file named by
COPY? - Does
FROMprovide the runtime version and operating-system variant the application expects? - Do the dependency manifests match the install command?
- Does the command in
CMDactually exist in the project and keep a service running when it should? - Will you use the same image name and tag in
docker runthat you supplied after-t?
These questions are deliberately simple: each corresponds to one boundary in the workflow, so a mistake can be corrected at the stage where it occurs.
Common beginner errors and how to diagnose them
| Symptom | Likely check | Correction |
|---|---|---|
| The Dockerfile cannot be found. | Check the directory from which you ran the command and whether the file is named exactly Dockerfile. |
Change to the intended project directory, pass the correct context, or select a different filename with the file option. |
A COPY instruction reports that a file is missing. |
Check the path in the Dockerfile and whether the file is inside the context represented by the final argument. | Use the correct context directory and adjust the source path to match the project layout. A file outside the context is not available to that build. |
| The dependency-install step fails. | Check that the selected base image contains the expected runtime and that the package manifests match the package manager command. | Choose a compatible base image or change the install instruction to the command used by the project. |
| The image builds but the container exits immediately. | Inspect the command declared by CMD and confirm that the application has the expected start script or executable. |
Set a valid startup command for this application. A command that completes normally will leave no running process to keep the container active. |
| The image has an unexpected name or version. | Check the argument after -t. |
Use an explicit repository name and tag, such as my-image:1.0, and use that exact reference with docker run. |
These checks separate three different problems: selecting the wrong files, building with an incompatible instruction, and starting the wrong command. Fix the earliest failing stage before changing later steps.
Run the image as a container
After a successful build, start the image with:
docker run --rm my-image:1.0The image reference must match the name and tag assigned during the build. The --rm option asks Docker to remove the container after it stops, which is convenient for a first local test. Remove that option when you need the stopped container to remain for later inspection.
Recommended Free Tools
If the application is a command-line task, it may print its result and exit. If it is a long-running service, the process specified by CMD must remain active. Exposing a service to your host may require additional run options that depend on the application’s listening port; those options are separate from creating the image itself.
When to use Buildx instead of the basic command
docker build is the simplest first lesson. Docker documents it as an alias for the Buildx build command, while Buildx exposes additional BuildKit controls. Use those controls when your project needs a non-default Dockerfile, a target platform, a particular stage, or a deliberate local-load or registry-push behavior.
| Reader need | Relevant option or pattern | Example |
|---|---|---|
| Use a Dockerfile with another filename | --file |
docker buildx build --file Dockerfile.dev -t my-image:1.0 . |
| Build for a specified target platform | --platform |
docker buildx build --platform linux/amd64 -t my-image:1.0 . |
| Select one stage from a multi-stage Dockerfile | --target |
docker buildx build --target production -t my-image:1.0 . |
| Load the result into the local image store | --load |
docker buildx build --load -t my-image:1.0 . |
| Send the build result directly to a registry | --push |
docker buildx build --push -t registry.example.com/team/my-image:1.0 . |
These examples show command controls, not a requirement to use Buildx for every project. The options and their current behavior are documented in docker buildx build. A multi-platform or registry workflow also requires choosing tags and destinations that match your own environment.
Choose the simplest workflow that fits
For a local first image, use the ordinary command and a local context. Choose --file only when the Dockerfile name differs. Add --platform when the target architecture or operating-system target is intentional. Add --target when a multi-stage Dockerfile contains a named stage that you specifically want. The --load and --push choices describe where the Buildx result should go: into the local image store or directly to a registry.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Those options solve different problems. A different filename is not a different context; a target stage is not a new application command; and pushing is not required merely because an image was built. Keeping these choices separate prevents a first tutorial from turning into an unnecessarily complex command.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose a suitable base image
The FROM line establishes the base image, so it should match the application’s runtime requirements. A base image that cannot run the required language version or native dependencies will fail during the build or when the container starts.
Docker’s base-image guidance says Docker Official Images have clear documentation, promote best practices, and are regularly updated. That makes documentation and maintenance history useful selection criteria, but it does not make one image universally correct. Confirm the version and variant your application supports rather than choosing solely because an image is small. See Base images for Docker’s guidance.
For the Node example, replace node:22-alpine if the project requires another Node release, a different operating-system variant, or tools not present in that base. Also adapt npm install and npm start to the project’s actual package-management and startup conventions.
Publishing is optional and separate
You do not need a registry to build or run an image on the same machine. Publish only when another machine, a deployment system, or another developer needs to pull the image.
A registry image reference includes the registry host and namespace. A typical separate workflow is:
- Build or retag the image with the destination registry and namespace, for example
<registry-host>/<namespace>/my-image:1.0. - Authenticate to that registry using its supported Docker authentication procedure.
- Push the tagged reference with
docker push <registry-host>/<namespace>/my-image:1.0.
Authentication and pushing are not implied by a successful local build. Docker’s official guide treats publishing as its own stage and documents docker push in Build, tag, and publish an image.
A practical decision guide
- Just learning or testing locally: use
docker build -t my-image:1.0 ., thendocker run --rm my-image:1.0. - Your Dockerfile has a different filename: use the file option and keep the final context argument pointed at the application files.
- You need a specific architecture or operating-system target: use the Buildx
--platformoption and choose a base image that supports that target. - You have multiple stages: use
--targetwhen you intentionally want one named stage rather than the Dockerfile’s final stage. - You want the result in a registry: give it the registry-qualified name, authenticate, and push; do not confuse that optional step with the local build.
Once the Dockerfile matches the application, the build context contains every required input, and the image has an explicit tag, the core process is complete: build the image, run a container from that image, and publish it only when distribution is required.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
How do I create a Docker image from my application folder?
Create an application-appropriate Dockerfile in the folder, then run docker build -t my-image:1.0 . from that folder. The final dot supplies the current directory as the build context.
What does the dot mean in docker build .?
It means “use the current directory” as the build context. Docker can use files in that directory and its subdirectories when the Dockerfile refers to them.
Is an image the same thing as a container?
No. Building creates the image. Running docker run creates a container from that image. The build does not start the application by itself.
Do I need to name my file Dockerfile?
No, but Dockerfile is the default name. If you use another filename, select it with the build command’s --file option; the final context argument remains separate.
Why does Docker say a file for COPY is missing?
The file may be outside the selected build context, the path may be wrong, or you may have run the command from the wrong directory. Choose a context that contains the required file and match the path in the Dockerfile.
What happens if I omit the image tag?
Docker uses the tag latest. An explicit tag such as 1.0 makes the intended image reference clear and should be reused with docker run.
Do I need Buildx to make my first image?
Not usually. docker build is the simplest first workflow. Buildx is useful when you need controls such as a different Dockerfile, a target platform, a selected multi-stage target, local loading, or direct registry pushing.
Why does my container exit immediately after it starts?
Check the command in CMD. A one-shot command can finish normally, while a service needs a valid startup process that remains active.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Must I publish an image to a registry?
No. You can build and run it locally without a registry. Publishing is a separate, optional step for sharing or deploying the image and requires registry authentication.
The Bottom Line
Creating a Docker image is a focused sequence: write a Dockerfile for the application, choose a context that contains every required input, build with an explicit tag, and run a container from that tag. In docker build -t my-image:1.0 ., the dot is the current-directory context, not decoration. Use Buildx options only when you need platform, stage, filename, loading, or pushing controls. Publish to a registry only when another system or person needs the image.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
