How to name Dockerfiles

Question

I'm unsure of how to name Dockerfiles. Many on GitHub use Dockerfile without a file extension. Do I give them a name and extension; if so what? Or do I just call them Dockerfile?

score 297 · Accepted Answer · edited Oct 20 '21 at 05:00

297

[Please read the full answer]Don't change the name of the dockerfile if you want to use the autobuilder at hub.docker.com. Don't use an extension for docker files, leave it null. File name should just be: (no extension at all)

Dockerfile

However, now you can name dockerfiles like,

test1.Dockerfile
$ docker build -f dockerfiles/test1.Dockerfile  -t test1_app .

or

Dockerfile.test1
$ docker build -f dockerfiles/Dockerfile.test1  -t test1_app .

This will also work.

If you handle multiple files that live in the same context, you could use STDIN:

test1.Dockerfile
$ docker build -t test1_app - < test1.Dockerfile

edited Oct 20 '21 at 05:00

Aosi

111
2
7

answered Sep 28 '14 at 10:33

tk_

16,415
8
80
90

162

What about when you have multiple Dockerfiles in the same directory? – Visgean Skeloru Aug 13 '16 at 12:12
@VisgeanSkeloru although a bit off a hassle you could put them in different directories if need be, no matter where I've looked it seem to be already established convention – orustammanapov Apr 06 '17 at 15:04
11

@VisgeanSkeloru Don't have multiple Dockerfiles in the same directory. The containing directory becomes the [context](https://docs.docker.com/engine/reference/builder/#usage) for the `docker build` command, which means that each image will be needlessly rebuilt if another image's dockerfile is changed. – Thomas Apr 26 '18 at 12:07
23

@Thomas sometimes you need to place multiple Dockerfiles in the same directory in order to share common files across separate containers, because docker context doesn't allow to access "../some-common-stuff" – Devis L. May 03 '19 at 20:30
13

Does the "D" have to be capitalized or it doesn't matter? – NoName Jun 13 '20 at 23:14
Hello Everyone, command to run such named Dockerfile is: docker build -t name/name -f test.Dockerfile . dot at the end is important! – Piotr Żak Oct 08 '20 at 19:57
I rolled back the answer to an earlier revision because it included a blatant copy from [another answer](https://stackoverflow.com/a/48879266/6707985). – geisterfurz007 Oct 19 '20 at 10:04
1

You could also use the STDIN to pass the file as an standard input: `docker build - < rarename.dockerfile` and should work – Aosi Oct 14 '21 at 01:18
@Aosi feel free to update the answer. – tk_ Oct 15 '21 at 02:15
1

Mind documenting where some of these recommendations are sourced from? Are these just gut feelings, or are they substantiated by any official best practice guides, special IDE support, or something else? – Jitsusama Jan 27 '22 at 14:59
If I run `docker build -f something.Dockerfile .` (where `something.Dockerfile` is a file in the CWD) it just opens a new terminal window then closes it immediately again, and seemingly no image is built. – Mitya Apr 12 '22 at 11:53
@Aosi: that only works for dockerfiles which don't need a build context (see https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#pipe-dockerfile-through-stdin), therefore I cannot make sense of your sentence `If you handle multiple files that live in the same context, you could use STDIN`. – David Ongaro Jul 08 '22 at 07:34

Sahil Ahuja · Answer 2 · 2019-03-11T09:10:15.747

164

dev.Dockerfile, test.Dockerfile, build.Dockerfile etc.

On VS Code I use <purpose>.Dockerfile and it gets recognized correctly.

edited Mar 11 '19 at 09:10

answered Feb 20 '18 at 06:36

Sahil Ahuja

2,225
1
16
12

3

Recognized correctly on IntelliJ Idea Community 2020.2 as well! – rahulmohan Nov 02 '20 at 13:38
11

to build image: docker build . -f dev.Dockerfile – Daniel B Jan 03 '21 at 18:20
1

How do you build with that? If I run `docker build -f foo.Dockerfile .` it just opens another terminal window (on top of the one I'm using) then closes it straight away and no image is built, with no error either. Weird. This is in Powershell, Windows. – Mitya Apr 12 '22 at 11:54
@Mitya, not sure. If it helps, my build command is `docker build -f base.Dockerfile .` in linux and it works. Does a normal build command work for you `docker build -f Dockerfile .` ? – Sahil Ahuja Apr 13 '22 at 05:14
Any time I specify `-f ` I get this weirdness with the new terminal window. The solution I worked out in the end was to use a docker-compose.yml and specify the Dockerfile in there via `build > dockerfile: foo.Dockerfile` – Mitya Apr 13 '22 at 10:29

score 72 · Answer 3 · edited Jul 02 '21 at 08:46

72

I know this is an old question, with quite a few answers, but I was surprised to find that no one was suggesting the naming convention used in the official documentation:

$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
$ docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .
The above commands will build the current build context (as specified by the .) twice, once using a debug version of a Dockerfile and once using a production version.

In summary, if you have a file called Dockerfile in the root of your build context it will be automatically picked up. If you need more than one Dockerfile for the same build context, the suggested naming convention is:

Dockerfile.<purpose>

These dockerfiles could be in the root of your build context or in a subdirectory to keep your root directory more tidy.

edited Jul 02 '21 at 08:46

Steve Chambers

37,270
24
156
208

answered Sep 21 '20 at 15:50

Erik B

40,889
25
119
135

13

It makes sense too because like this, when sorted alphabetically and sitting alongside other files in a directory, all Dockerfiles are grouped together. – haslo Jan 06 '21 at 11:13
3

That reasoning can be applied to all files, yet by convention we have extentions, i.e. types of files, as suffix to the filename. – hbogert Jan 13 '21 at 13:29
6

The problem is that `.purpose` is now the extension of your file, which might confuse the system, text-editor or IDEs. `.Dockerfile` has the advantage of always having `.Dockerfile` as extension – Eric Duminil Dec 19 '21 at 10:09
2

Read the docs you linked and it does include references to both naming formats such as using `.Dockerfile` as the extension. From the official docs: `For example, running docker build -f myapp.Dockerfile . will first look for an ignore file...`. From here: https://docs.docker.com/engine/reference/commandline/build/#use-a-dockerignore-file – Levi Fuller Jan 12 '23 at 20:28
Having that capital "D" in the extension just doesn't sit right with me. :) – Josh M. Apr 26 '23 at 20:36

score 39 · Answer 4 · answered Mar 15 '17 at 13:07

39

I think you should have a directory per container with a Dockerfile (no extension) in it. For example:

  /db/Dockerfile
  /web/Dockerfile
  /api/Dockerfile

When you build just use the directory name, Docker will find the Dockerfile. e.g:

docker build -f ./db .

answered Mar 15 '17 at 13:07

garryp

5,508
1
29
41

Will it build 3 containers from your example? – alvas Apr 11 '17 at 01:56
@alvas Yes it will – garryp Apr 11 '17 at 09:02
10

It is not good enough many cases. Docker can not see files up. For example target, build, etc. – Cyva Nov 09 '17 at 10:14
Can we run this 3 docker file at single time using docker-compose command then? – Yogi Ghorecha Jan 08 '20 at 13:00
1

but this is why docker compose is good to use instead IMO. Then it's very flexible how you wanna structure or locate your actual dockerfile(s) – PositiveGuy Sep 14 '20 at 04:47
This method has the advantage of passing a smaller build context. If you have a lot of content in the main folder, passing "." as build context - when using dev.dockerfile, etc. - may slowdown building every image as all context is always passed to each image... – codea Apr 13 '21 at 21:02
@Cyva: not true. The Dockerfile directory and the build context path are independent of each other. – David Ongaro Jul 08 '22 at 07:14
I tried this structure years ago and it just made it a pain to search for Dockerfiles as they all had the same name – Shardj Jul 07 '23 at 15:21

score 26 · Answer 5 · edited Jan 02 '19 at 10:26

26

I have created two Dockerfiles in same directory,

# vi one.Dockerfile
# vi two.Dockerfile

to build both Dockerfiles use,

# docker build . -f one.Dockerfile
# docker build . -f two.Dockerfile

Note: you should be in present working directory..

edited Jan 02 '19 at 10:26

Brian Tompsett - 汤莱恩

5,753
72
57
129

answered Jan 02 '19 at 10:21

Shivaraj Navalgund

337
4
3

score 23 · Answer 6 · answered Jul 06 '18 at 07:46

Do I give them a name and extension; if so what?

You may name your Dockerfiles however you like. The default filename is Dockerfile (without an extension), and using the default can make various tasks easier while working with containers.

Depending on your specific requirements you may wish to change the filename. If you're building for multiple architectures, for example, you may wish to add an extension indicating the architecture as the resin.io team has done for the HAProxy container their multi-container ARM example:

Dockerfile.aarch64
Dockerfile.amd64
Dockerfile.armhf
Dockerfile.armv7hf
Dockerfile.i386
Dockerfile.i386-nlp
Dockerfile.rpi

In the example provided, each Dockerfile builds from a different, architecture-specific, upstream image. The specific Dockerfile to use for the build may be specified using the --file, -f option when building your container using the command line.

I like using an extension to indicate architecture (or whatever). Unlike some other answers, all the Dockerfiles are dead simple to find in a big, cluttered directory; they naturally sort together. — Mike Sherrill 'Cat Recall', Feb 03 '19 at 18:07

score 21 · Answer 7 · answered Sep 27 '14 at 18:05

21

If you want to use the autobuilder at hub.docker.com, it has to be Dockerfile. So there :)

answered Sep 27 '14 at 18:05

Dirk Eddelbuettel

360,940
56
644
725

4

I believe the context of the question was more broad. Perhaps you could include additional information for individuals not using _autobuilder_ to make this answer more complete. – vhs Jul 06 '18 at 07:07

score 19 · Answer 8 · answered Oct 10 '16 at 13:50

It seems this is true but, personally, it seems to me to be poor design. Sure, have a default name (with extension) but allow other names and have a way of specifying the name of the docker file for commands.

Having an extension is also nice because it allows one to associate applications to that extension type. When I click on a Dockerfile in MacOSX it treats it as a Unix executable and tries to run it.

If Docker files had an extension I could tell the OS to start them with a particular application, e.g. my text editor application. I'm not sure but the current behaviour may also be related to the file permisssions.

I prefer using .Dockerfile in such a scenario. Works well with Jetbrains IDEs as well. — Nishant, Mar 03 '21 at 14:35

score 5 · Answer 9 · edited May 27 '23 at 03:14

5

Dockerfile is good if you only have one docker file (per-directory). You can use whatever standard you want if you need multiple docker files in the same directory - if you have a good reason. In a recent project there were AWS docker files and local dev environment files because the environments differed enough:

Dockerfile
Dockerfile.aws

edited May 27 '23 at 03:14

Gino Mempin

25,369
29
96
135

answered Nov 20 '17 at 15:33

ktamlyn

4,519
2
30
41

1

I've seen this method used for specifying architectures as well. For example, placing a `Dockerfile.armv7hf` next to a `Dockerfile.i386`. – vhs Jul 06 '18 at 07:05

Surjitsing Chundunsing · Answer 10 · 2022-03-25T11:08:36.060

There are 2 main Dockerfile naming conventions:

1. Using a default Dockerfile:

Keeping it simple, this approach suits simple, standalone, and well-defined projects.

$ docker build -f ./Dockerfile.Dockerfile .

2. Using a custom Dockerfile:

Keeping it custom, this approach familiarises the developer with the application context, facilitates file manipulation and, improves debugging capability, especially in the case of multiple dockerfiles.

$ docker build -t <containername> . -f <mycustomdockerfile>.Dockerfile

Gentle Reminder:

These conventions are equally applicable for common docker image building commands such as 'docker image build' and 'docker-compose build'.

score 3 · Answer 11 · answered May 28 '20 at 22:49

3

Dockerfile (custom name and folder):

   docker/app.Dockerfile
   docker/nginx.Dockerfile

Build:

   docker build  -f ./docker/app.Dockerfile .
   docker build  -f ./docker/nginx.Dockerfile .

answered May 28 '20 at 22:49

Abel

3,989
32
31

How to name Dockerfiles

11 Answers11

Linked