158 lines
6.5 KiB
Markdown
158 lines
6.5 KiB
Markdown
---
|
|
obj: concept
|
|
source: https://docs.docker.com/engine/reference/builder
|
|
---
|
|
|
|
# Dockerfile
|
|
A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. It is used to build container images.
|
|
|
|
## Format
|
|
```dockerfile
|
|
# Comment
|
|
INSTRUCTION arguments
|
|
```
|
|
|
|
You can use environment variable expansion:
|
|
```dockerfile
|
|
FROM busybox
|
|
ENV FOO=/bar
|
|
WORKDIR ${FOO} # WORKDIR /bar
|
|
ADD . $FOO # ADD . /bar
|
|
COPY \$FOO /quux # COPY $FOO /quux
|
|
```
|
|
|
|
If you have a `.dockerignore` file, you can exclude certain files from the build context. The file is formatted like a `.gitignore`.
|
|
|
|
## Instructions
|
|
### `FROM`
|
|
The `FROM` instruction initializes a new build stage and sets the Base Image for subsequent instructions. As such, a valid Dockerfile must start with a `FROM` instruction.
|
|
```dockerfile
|
|
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
|
|
```
|
|
|
|
You can also start from nothing:
|
|
```
|
|
FROM SCRATCH
|
|
```
|
|
|
|
### `RUN`
|
|
The `RUN` instruction will execute any commands in a new layer on top of the current image and commit the results. The resulting committed image will be used for the next step in the Dockerfile.
|
|
The `RUN` command has two forms:
|
|
- Shell form (the command is run in a shell): `RUN <command>`
|
|
- Exec form: `RUN ["executable", "param1", "param2"]`
|
|
|
|
`RUN --mount` allows you to create filesystem mounts that the build can access.
|
|
```dockerfile
|
|
# Bind Mount
|
|
RUN --mount=type=bind,source=/path,target=/path CMD
|
|
|
|
# TmpFs
|
|
RUN --mount=type=tmpfs,target=path,size=20G CMD
|
|
```
|
|
|
|
### `CMD`
|
|
The main purpose of a `CMD` is to provide defaults for an executing container. These defaults can include an executable, or they can omit the executable, in which case you must specify an `ENTRYPOINT` instruction as well.
|
|
There can only be one `CMD` instruction in a Dockerfile. If you list more than one `CMD` then only the last `CMD` will take effect.
|
|
The `CMD` instruction has three forms:
|
|
- Exec form (preferred): `CMD ["executable","param1","param2"]`
|
|
- As default parameters to `ENTRYPOINT`: `CMD ["param1","param2"]`
|
|
- Shell form: `CMD command param1 param2`
|
|
|
|
### `LABEL`
|
|
The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and backslashes as you would in command-line parsing.
|
|
```dockerfile
|
|
LABEL "com.example.vendor"="ACME Incorporated"
|
|
LABEL com.example.label-with-value="foo"
|
|
LABEL version="1.0"
|
|
LABEL description="This text illustrates \
|
|
that label-values can span multiple lines."
|
|
```
|
|
|
|
### `EXPOSE`
|
|
The `EXPOSE` instruction informs [Docker](Docker.md) that the container listens on the specified network ports at runtime. You can specify whether the port listens on [TCP](../internet/TCP.md) or [UDP](../internet/UDP.md), and the default is [TCP](../internet/TCP.md) if the protocol is not specified.
|
|
The `EXPOSE` instruction does not actually publish the port. It functions as a type of documentation between the person who builds the image and the person who runs the container, about which ports are intended to be published.
|
|
```dockerfile
|
|
EXPOSE <port> [<port>/<protocol>...]
|
|
```
|
|
|
|
### `ENV`
|
|
The `ENV` instruction sets the environment variable `<key>` to the value `<value>`.
|
|
```dockerfile
|
|
ENV <key>=<value> ...
|
|
ENV MY_NAME="John Doe"
|
|
ENV MY_DOG=Rex\ The\ Dog
|
|
ENV MY_CAT=fluffy
|
|
```
|
|
|
|
### `ADD`
|
|
The `ADD` instruction copies new files, directories or remote file URLs from `<src>` and adds them to the filesystem of the image at the path `<dest>`.
|
|
```dockerfile
|
|
ADD [--chown=<user>:<group>] [--chmod=<perms>] [--checksum=<checksum>] <src>... <dest>
|
|
ADD [--chown=<user>:<group>] [--chmod=<perms>] ["<src>",... "<dest>"]
|
|
|
|
# Checksums and remote files
|
|
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz /
|
|
|
|
# Add a git repository
|
|
ADD --keep-git-dir=true https://github.com/moby/buildkit.git#v0.10.1 /buildkit
|
|
```
|
|
|
|
### `COPY`
|
|
The `COPY` instruction copies new files or directories from `<src>` and adds them to the filesystem of the container at the path `<dest>`.
|
|
```dockerfile
|
|
COPY [--chown=<user>:<group>] [--chmod=<perms>] <src>... <dest>
|
|
COPY [--chown=<user>:<group>] [--chmod=<perms>] ["<src>",... "<dest>"]
|
|
```
|
|
|
|
You can also copy between multistaged builds:
|
|
```dockerfile
|
|
FROM alpine as builder
|
|
RUN touch /test.txt
|
|
FROM ubuntu
|
|
COPY --from=builder /test.txt /
|
|
```
|
|
|
|
### `ENTRYPOINT`
|
|
An `ENTRYPOINT` allows you to configure a container that will run as an executable.
|
|
Command line arguments to docker run `<image>` will be appended after all elements in an exec form `ENTRYPOINT`, and will override all elements specified using `CMD`.
|
|
```dockerfile
|
|
ENTRYPOINT ["executable", "param1", "param2"]
|
|
```
|
|
|
|
### `VOLUME`
|
|
The `VOLUME` instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers.
|
|
```dockerfile
|
|
VOLUME ["/data"]
|
|
```
|
|
|
|
### `USER`
|
|
The `USER` instruction sets the user name (or UID) and optionally the user group (or GID) to use as the default user and group for the remainder of the current stage. The specified user is used for `RUN` instructions and at runtime, runs the relevant `ENTRYPOINT` and `CMD` commands.
|
|
```dockerfile
|
|
USER <user>[:<group>]
|
|
USER <UID>[:<GID>]
|
|
```
|
|
|
|
### `WORKDIR`
|
|
The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the Dockerfile. If the `WORKDIR` doesn't exist, it will be created even if it's not used in any subsequent Dockerfile instruction.
|
|
```dockerfile
|
|
WORKDIR /path/to/workdir
|
|
```
|
|
|
|
### `HEALTHCHECK`
|
|
The `HEALTHCHECK` instruction tells [Docker](Docker.md) how to test a container to check that it is still working. This can detect cases such as a web server that is stuck in an infinite loop and unable to handle new connections, even though the server process is still running.
|
|
When a container has a healthcheck specified, it has a health status in addition to its normal status. This status is initially starting. Whenever a health check passes, it becomes healthy (whatever state it was previously in). After a certain number of consecutive failures, it becomes unhealthy.
|
|
```dockerfile
|
|
HEALTHCHECK [OPTIONS] CMD command
|
|
```
|
|
|
|
The options that can appear before CMD are:
|
|
- `--interval=DURATION` (default: 30s)
|
|
- `--timeout=DURATION` (default: 30s)
|
|
- `--start-period=DURATION` (default: 0s)
|
|
- `--start-interval=DURATION` (default: 5s)
|
|
- `--retries=N` (default: 3)
|
|
|
|
```dockerfile
|
|
HEALTHCHECK --interval=5m --timeout=3s \
|
|
CMD curl -f http://localhost/ || exit 1
|
|
```
|