Welcome! We’re excited that you want to learn Docker.

This guide contains step-by-step instructions on how to get started with Docker. Some of the things you’ll learn and do in this guide are:

• Build and run an image as a container.
• Share images using Docker Hub
• Deploy Docker applications using multiple containers with a database.
• Run applications using Docker Compose.

Before you get to the hands on part of the guide, you should learn about containers and images.

Simply put, a container is a sandboxed process on your machine that is isolated from all other processes on the host machine. That isolation leverages kernel namespaces and cgroups, features that have been in Linux for a long time. Docker has worked to make these capabilities approachable and easy to use. To summarize, a container:

• Is a runnable instance of an image. You can create, start, stop, move, or delete a container using the DockerAPI or CLI.
• Can be run on local machines, virtual machines or deployed to the cloud.
• Is portable (can be run on any OS).
• Is isolated from other containers and runs its own software, binaries, and configurations.

When running a container, it uses an isolated filesystem. This custom filesystem is provided by a container image. Since the image contains the container’s filesystem, it must contain everything needed to run an application - all dependencies, configurations, scripts, binaries, etc. The image also contains other configuration for the container, such as environment variables, a default command to run, and other metadata.

You’ll dive deeper into images later on in this guide, covering topics such as layering, best practices, and more.

note

If you’re familiar with chroot, think of a container as a extended version of chroot. The filesystem is simply comming from the image. But, a container adds aditional isolation not available when simply using chroot.

For the rest of this guide, you’ll be working with a simple todo list manager that runs on Node.js. If you’re not familiar with Node.js, don’t worry. This guide doesn’t require any prior experience with JavaScript.

To complete this guide, you’ll need the following:

• Docker running locally. Follow the instructions to download and install Docker.
• A Git client
• An IDE or a text editor to edit files. Docker recommends using Visual Studio Code.
• A conceptual understanding of containers and images.

Before you can run the application, you need to get the application source code onto your machine.

1. Clone the getting-started repository using the following command:

   $ git clone https://github.com/docker/getting-started.git

2. View the contents of the cloned repository. Inside the getting-started/app directory you should see package.json and two subdirectories (src and spec).

   

To build the container image, you’ll need to use a Dockerfile. A Dockerfile is simply a text-based file with no file extension that contains a script of instructions. Docker uses this script to build a container image.

1. In the app directory, the same location as the package.json file, create a file named Dockerfile. You can use the following commands below to create a Dockerfile based on Linux/Mac.

   In the terminal, run the following commands listed below

   Change directory to the app directory. Replace /path/to/app with the path to you getting-started/app directory.

   $ cd /path/to/app

   Create an empty file named Dockerfile.

   $ touch Dockerfile

2. Using a text editor or code editor, add the following contents to the Dockerfile:

   # syntax=docker/dockerfile:1
      
   FROM node:18-alpine
   WORKDIR /app
   COPY . .
   RUN yarn install --production
   CMD ["node", "src/index.js"]
   EXPOSE 3000

3. Build the container image using the following commands:

   In the terminal, change directory to the getting-started/app directory. Replace /path/to/app with the path to your getting-started/app directory.

   $ cd /path/to/app

   Build the container image.

   $ docker build -t getting-started .

   The docker build command uses the Dockerfile to build a new container image. You might have noticed that Docker downloaded a lot of “layers”. This is because you instructed the builder that you wanted to start from the node:18-alpine image. But, since you didn’t have that on your machine, Docker needed to download the image.

   After Docker downloaded the image, the instructions from the Dockerfile copied in your application and used yarn to install your application’s dependencies. The CMD directive specifies the default command to run when starting a container from this image.

   Finally, the -t flag tags your image. Think of this simply as a human-readable name for the final image. Since you named the image getting-started, you can refer to that image when you run a container.

   The . at the end of the docker build command tells Docker that it should look for the Dockerfile in the current directory

Now that you have an image, you can run the application in a container. To do so, you will use the docker run command.

1. Start your container using the docker run command and specify the name of the image you just created

   $ docker run -dp 127.0.0.1:3000:3000 getting-started

   The -f flag (short for --detached) runs the container in the background. The -p flag (short for --publish) creates a port mapping between the host and the container. The -p flag take a string value in the format of HOST:CONTAINER, where the HOST is the address on the host, and CONTAINER is the port on the container. The command shown here publishes the container’s port 3000 to 127.0.0.1:3000 (localhost:3000) on the host. Without the port mapping, you wouldn’t be able to access the application from the host.

2. After a few seconds, open your web browser to http://localhost:3000. You should see your app.

   

3. Go ahead and add an item or two and see that it works as you expect. You can mark items as complete and remove them. Your frontend is successfully storing items in the backend.

At this point, you should have a running todo list manager with a few items, all built by you.