# Introduction

## Introduction <a href="#title" id="title"></a>

This guide illustrates various ways that you can **improve** how you build the application with Docker.

### 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:

```
.
├── 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:

```docker
# syntax=docker/dockerfile:1
FROM golang:1.20-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](https://docs.docker.com/engine/reference/builder/#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:1.20-alpine`

   The `FROM` instruction uses version `1.20-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, 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.

```docker
$ 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.

   ```
   $ 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.

   ```
   $ 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:

```
$ 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raviram.gitbook.io/docker/layers-and-stages/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.