Skip to main content
Docker for Beginners: Build, Run, and Ship Your First Container

Docker for Beginners: Build, Run, and Ship Your First Container

KU
· Founder & Chief Editor
• 7 min read•Updated •53 views

Walk through your first Dockerfile, container run, and image push in 30 minutes. No theory dumps, just the commands and what each one is doing.

Key takeaways

  • Your first container takes three commands.
  • Write a Dockerfile, run docker build -t hello:1 . to make an image, then docker run -p 8000:8000 hello:1 to start it with the port published.
  • Tag the image with your Docker Hub username and run docker push to ship it anywhere.

To run your first container, write a four-line Dockerfile, build it with docker build -t hello:1 ., start it with docker run --rm -p 8000:8000 hello:1, then docker tag and docker push it to Docker Hub. Build, run, ship: everything else in Docker is a variation on those three steps.

Verified against

Docker Engine 29.9 (29.9.2, released 2026-10-20), python:3.14-slim from the Docker Hub official image, against the docs.docker.com Get started guide and Dockerfile reference. Checked October 2026.

By the end of this post you'll have built an image from a tiny Python web app, run it locally, and pushed it to Docker Hub, and you'll know what each command actually does. You need Docker installed (Docker Desktop on Mac or Windows, Docker Engine on Linux), a free Docker Hub account, and about 30 minutes.

What a container actually is

A container is a regular Linux process running with extra kernel features that make it think it's alone on the machine. Its filesystem is isolated, its network is its own, its process tree starts fresh at PID 1. But it shares the host kernel; there's no second OS booting up.

That's why containers start in about the time it takes to start the process itself, while VMs boot a whole operating system. They're not little operating systems. They're processes with isolation applied, and the limits on CPU and memory come from cgroups, which we unpack in what actually constrains a container.

A Docker image is a packaged filesystem plus metadata telling Docker how to start the container. You build images from a Dockerfile, run them as containers, and ship them by pushing to a registry.

Step 1: Verify Docker works

code
$ docker --version
$ docker run hello-world

Docker prints its version, then pulls and runs the hello-world test image, which prints a message confirming everything works. If this fails, fix Docker before moving on; nothing else will work. A "permission denied" on Linux means your user can't reach the daemon socket, and the Docker permission denied fix covers it.

Step 2: Write a tiny app

Make a new directory:

code
$ mkdir docker-tutorial && cd docker-tutorial

Then create app.py:

Python
# docker-tutorial/app.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import os

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.end_headers()
        self.wfile.write(f"Hello from {os.uname().nodename}\n".encode())

if __name__ == "__main__":
    HTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

That's a minimal HTTP server. No framework, no dependencies, pure standard library. It listens on port 8000 and responds with the hostname. Binding to 0.0.0.0 matters: a server bound to 127.0.0.1 inside a container is unreachable from outside it.

Test it locally first:

code
$ python3 app.py &
$ curl http://localhost:8000
Hello from your-laptop-name
$ kill %1

If that works, the app is fine, and any issue from here on is container-related, not code.

Step 3: Write the Dockerfile

Create Dockerfile in the same directory:

Dockerfile
# docker-tutorial/Dockerfile
FROM python:3.14-slim

WORKDIR /app

COPY app.py .

EXPOSE 8000

CMD ["python", "app.py"]

Each instruction:

  • FROM python:3.14-slim: start from the official Python image. slim leaves out build tools we don't need. As of October 2026 Docker Hub still lists 3.12-slim and 3.13-slim too; pin the minor version you test against.
  • WORKDIR /app: set the working directory inside the image. Later instructions run relative to it.
  • COPY app.py .: copy the local app.py into /app/app.py inside the image.
  • EXPOSE 8000: document that the container listens on 8000. The Dockerfile reference is blunt: "The EXPOSE instruction doesn't actually publish the port."
  • CMD ["python", "app.py"]: what to run when the container starts. The JSON (exec) form runs Python directly, so it receives signals like Ctrl-C.

That's a complete Dockerfile. No tricks.

Step 4: Build the image

code
$ docker build -t hello:1 .

The -t hello:1 tags the image as hello with tag 1. The . is the build context: the directory whose files Docker may copy into the image. BuildKit prints one line per step, ending with the image being named docker.io/library/hello:1.

Confirm it exists:

code
$ docker image ls hello

You should see hello with tag 1 and an image ID. The exact columns differ between Docker versions, so don't worry if yours look different from a screenshot somewhere.

Step 5: Run it

code
$ docker run --rm -p 8000:8000 --name hello hello:1

Flag breakdown:

  • --rm: delete the container when it stops, so dead containers don't pile up
  • -p 8000:8000: publish container port 8000 on host port 8000 (format host:container)
  • --name hello: a friendly name to refer to it by
  • hello:1: the image to run

In a second terminal:

code
$ curl http://localhost:8000
Hello from 3f2a9c1b7d4e

That hex string is the container's hostname, different from your laptop's because the container has its own UTS namespace. That's isolation in action. Stop it with Ctrl-C in the first terminal.

Step 6: Push it

Sign up for a free Docker Hub account if you don't have one. Then:

code
$ docker login
$ docker tag hello:1 yourusername/hello:1
$ docker push yourusername/hello:1

Replace yourusername with your Docker Hub username. After the push completes, anyone (including you, on another machine) can pull and run it:

code
$ docker run --rm -p 8000:8000 yourusername/hello:1

If that other machine is an ARM server or an Apple Silicon Mac and you built on x86, you may hit an architecture mismatch; multi-arch builds with buildx produce one tag that runs on both.

Common mistakes

Forgetting the port mapping. docker run hello:1 (without -p) starts the container but doesn't publish its port, so curl localhost:8000 fails. Always remember -p host:container.

Building with no tag. docker build . (without -t) creates an image with no name. You can run it by ID, but it's annoying. Always tag.

Editing files inside the running container. Changes inside a container's filesystem are lost when the container is removed (unless you mounted a volume). Edit on the host, rebuild, re-run.

Using :latest for everything. latest is just the default tag name, not "newest". When you push v2 to :latest, anyone pulling it silently gets the new version. Use real version tags (:1, :1.2.3, a git SHA) in production.

Questions people ask

What is the difference between a Docker image and a container?

An image is a read-only package: a layered filesystem plus metadata such as the default command and exposed ports. A container is a running (or stopped) instance of an image, with its own writable layer, network namespace and process tree. One image can back many containers at once. You build and push images; you run, stop and remove containers.

Why can't I reach my container on localhost?

Usually one of two things. Either you didn't publish the port, so add -p 8000:8000 to docker run, because EXPOSE alone publishes nothing. Or the app inside binds to 127.0.0.1, which only accepts connections from inside the container itself; bind to 0.0.0.0 instead. Check what's published with docker ps, which shows the port mappings for each running container.

Do I need Docker Desktop to learn Docker?

On Linux, no: install Docker Engine from your distribution's Docker repository and everything in this tutorial works. On macOS and Windows, containers need a Linux kernel, so you need something that runs a lightweight VM, and Docker Desktop is the official option. Check Docker's current licensing terms if you use Desktop at a larger company.

You've got the bones. The next levels:

Docker isn't a complicated technology. Once you've shipped one image you've used most of the surface area. The rest is patterns.

Sources

Explore topics:DockerDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). Docker for Beginners: Build, Run, and Ship Your First Container. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/docker-beginners-tutorial-first-container

Markdown

[Docker for Beginners: Build, Run, and Ship Your First Container](https://www.devopsness.com/blog/docker-beginners-tutorial-first-container) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

586 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.