mirror of https://github.com/docker/docs.git
173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
---
|
||
title: Introduction
|
||
description: An introduction to the Docker Build guide
|
||
keywords: build, buildkit, buildx, guide, tutorial, introduction
|
||
---
|
||
|
||
{% include_relative nav.html selected="1" %}
|
||
|
||
The starting resources for this guide include a simple Go project and a
|
||
Dockerfile. From this starting point, the guide illustrates various ways that
|
||
you can improve how you build the application with Docker.
|
||
|
||
## Environment setup
|
||
|
||
To follow this guide:
|
||
|
||
1. Install [Docker Desktop or Docker Engine](../../get-docker.md)
|
||
2. Clone or create a new repository from the
|
||
[application example on GitHub](https://github.com/dockersamples/buildme)
|
||
|
||
## The application
|
||
|
||
The example project for this guide is a client-server application for
|
||
translating messages to a fictional language.
|
||
|
||
Here’s an overview of the files included in the project:
|
||
|
||
```text
|
||
.
|
||
├── Dockerfile
|
||
├── cmd
|
||
│ ├── client
|
||
│ │ ├── main.go
|
||
│ │ ├── request.go
|
||
│ │ └── ui.go
|
||
│ └── server
|
||
│ ├── main.go
|
||
│ └── translate.go
|
||
├── go.mod
|
||
└── go.sum
|
||
```
|
||
|
||
The `cmd/` directory contains the code for the two application components:
|
||
client and server. The client is a user interface for writing, sending, and
|
||
receiving messages. The server receives messages from clients, translates them,
|
||
and sends them back to the client.
|
||
|
||
## The Dockerfile
|
||
|
||
A Dockerfile is a text document in which you define the build steps for your
|
||
application. You write the Dockerfile in a domain-specific language, called the
|
||
Dockerfile syntax.
|
||
|
||
Here's the Dockerfile used as the starting point for this guide:
|
||
|
||
```dockerfile
|
||
# syntax=docker/dockerfile:1
|
||
FROM golang:{{site.example_go_version}}-alpine
|
||
WORKDIR /src
|
||
COPY . .
|
||
RUN go mod download
|
||
RUN go build -o /bin/client ./cmd/client
|
||
RUN go build -o /bin/server ./cmd/server
|
||
ENTRYPOINT [ "/bin/server" ]
|
||
```
|
||
|
||
Here’s what this Dockerfile does:
|
||
|
||
1. `# syntax=docker/dockerfile:1`
|
||
|
||
This comment is a
|
||
[Dockerfile parser directive](../../engine/reference/builder.md#parser-directives).
|
||
It specifies which version of the Dockerfile syntax to use. This file uses
|
||
the `dockerfile:1` syntax which is best practice: it ensures that you have
|
||
access to the latest Docker build features.
|
||
|
||
2. `FROM golang:{{site.example_go_version}}-alpine`
|
||
|
||
The `FROM` instruction uses version `{{site.example_go_version}}-alpine` of the `golang` official image.
|
||
|
||
3. `WORKDIR /src`
|
||
|
||
Creates the `/src` working directory inside the container.
|
||
|
||
4. `COPY . .`
|
||
|
||
Copies the files in the build context to the working directory in the
|
||
container.
|
||
|
||
5. `RUN go mod download`
|
||
|
||
Downloads the necessary Go modules to the container. Go modules is the
|
||
dependency management tool for the Go programming language, similar to
|
||
`npm install` for JavaScript, or `pip install` for Python.
|
||
|
||
6. `RUN go build -o /bin/client ./cmd/client`
|
||
|
||
Builds the `client` binary, which is used to send messages to be translated, into the
|
||
`/bin` directory.
|
||
|
||
7. `RUN go build -o /bin/server ./cmd/server`
|
||
|
||
Builds the `server` binary, which listens for client translation requests,
|
||
into the `/bin` directory.
|
||
|
||
8. `ENTRYPOINT [ "/bin/server" ]`
|
||
|
||
Specifies a command to run when the container starts. Starts the server
|
||
process.
|
||
|
||
## Build the image
|
||
|
||
To build an image using a Dockerfile, you use the `docker` command-line tool.
|
||
The command for building an image is `docker build`.
|
||
|
||
Run the following command to build the image.
|
||
|
||
```console
|
||
$ docker build --tag=buildme .
|
||
```
|
||
|
||
This creates an image with the tag `buildme`. An image tag is the name of the
|
||
image.
|
||
|
||
## Run the container
|
||
|
||
The image you just built contains two binaries, one for the server and one for
|
||
the client. To see the translation service in action, run a container that hosts
|
||
the server component, and then run another container that invokes the client.
|
||
|
||
To run a container, you use the `docker run` command.
|
||
|
||
1. Run a container from the image in detached mode.
|
||
|
||
```console
|
||
$ docker run --name=buildme --rm --detach buildme
|
||
```
|
||
|
||
This starts a container named `buildme`.
|
||
|
||
2. Run a new command in the `buildme` container that invokes the client binary.
|
||
|
||
```console
|
||
$ docker exec -it buildme /bin/client
|
||
```
|
||
|
||
The `docker exec` command opens a terminal user interface where you can submit
|
||
messages for the backend (server) process to translate.
|
||
|
||
When you're done testing, you can stop the container:
|
||
|
||
```console
|
||
$ docker stop buildme
|
||
```
|
||
|
||
## Summary
|
||
|
||
This section gave you an overview of the example application used in this guide,
|
||
an introduction to Dockerfiles and building. You've successfully built a
|
||
container image and created a container from it.
|
||
|
||
Related information:
|
||
|
||
- [Dockerfile reference](../../engine/reference/builder.md)
|
||
- [`docker build` CLI reference](../../engine/reference/commandline/build.md)
|
||
- [`docker run` CLI reference](../../engine/reference/commandline/run.md)
|
||
|
||
## Next steps
|
||
|
||
The next section explores how you can use layer cache to improve build speed.
|
||
|
||
[Layers](layers.md){: .button .primary-btn }
|