What Is Docker Init? Files, Languages, and Best Practices

Every new service starts the same way. You open an empty Dockerfile, go looking for the right base image, copy a multi-stage build from whatever project you touched last, and hope you remembered to exclude node_modules. Multiply that across a dozen repositories and you get a dozen slightly different Dockerfiles that nobody owns. 

docker init removes that step. Run it in a project directory, answer a handful of prompts, and Docker Desktop writes a Dockerfile, compose.yaml, .dockerignore, and README.Docker.md tuned to your language. You get a working starting point in about a minute, and every project in your organization starts from the same one.

Docker announced docker init as a beta in May 2023 and made it generally available in February 2024 with Docker Desktop 4.27. That release brought the template count to seven languages and frameworks plus a generic option.

In this artice, we’ll explore docker init in this article by discussing when it’s useful and showing how to get started.

We’ll cover:

1. What is docker init?
2. When to use docker init?
3. How to use docker init – example
4. docker init vs Gordon (docker ai)
5. Best practices for using docker init

docker init is a Docker Desktop CLI command that sets up a basic Docker project by creating essential files like Dockerfile, .dockerignore, and sometimes docker-compose.yml. It prompts for your application platform, the language version you want, the command that starts your app, and the port your server listens on, then writes four files based on your answers. The exact prompts vary by template.

It gets a supported project from zero to a running container without you writing a Dockerfile by hand, which makes it useful for bootstrapping new services and for engineers meeting Docker for the first time. You will still tune the output before production.

Why is docker init useful?

Before an app can be run in a Docker container, it must first be built into a Docker image. Images package your code and dependencies into portable units that define your container’s initial filesystem. Images are created from Dockerfiles that contain instructions listing the files to copy and the commands to run to assemble the filesystem.

Dockerfiles can become quite complex, even for relatively simple apps. Your Dockerfile will typically need to include the following steps:

1. Select a base image that provides your container’s OS and programming runtime, such as ubuntu:26.04 or node:24.
2. Install any additional OS packages, programming languages, and frameworks your project requires.
3. Fetch your project’s programming language dependencies, for example with npm, Cargo, or Gradle.
4. Copy in your source code.
5. Perform any filesystem or environment changes that are required by your app.

docker init ships Dockerfile templates that cover these steps for ASP.NET Core, Go, Java, Node, PHP with Apache, Python, and Rust. It writes a ready-to-use Dockerfile and supporting files into your project, so you can build your image and start a container straight away.

What files does docker init create?

docker init writes four files to your project:

• Dockerfile — Describes how to build your image, using the base image, dependency install steps, and start command for your language.
• compose.yaml — Starts your app and the services it depends on, such as a database, as a set of containers.
• .dockerignore — Excludes paths that image builds don’t need. Keeping them out of the build context means less content sent to the builder and smaller images. docker init excludes common paths like dependency folders, which your package manager recreates during the build anyway
• README.Docker.md – Documents how to build, run, and deploy the generated setup. Docker’s CLI output points you here when it finishes

These four files give you everything you need to containerize a simple app.

Which languages does docker init support?

docker init offers seven language and framework templates plus a generic option. Each one asks a slightly different set of questions.

Template	What it prompts for
ASP.NET Core	Main project name, .NET version, local port
Go	Go version, relative directory of your main package, port
Java	Java version, relative app directory, port. Expects Maven and packages as an uber jar
Node	Node version, package manager, whether to run a build step, build output directory, start command, port
PHP with Apache	PHP version, relative app directory, local port. Add any PHP extensions to the Dockerfile yourself
Python	Python version, port, command to run your app
Rust	Rust version, port
Other	Nothing. Writes generic, commented files for you to fill in

If docker init detects your project type, it preselects the matching template.

docker init vs docker-init

A potential source of confusion for docker init users is the command’s obvious similarity to docker-init, a standalone binary that Docker uses as the init process inside a container when you run it with –init.

docker init and docker-init are entirely separate tools. Use docker init to scaffold configuration in your projects. docker-init is an internal utility, and you never invoke it yourself.

Docker Init is helpful in several real-world development scenarios:

• Quickly bootstrap new projects: You can quickly bootstrap new apps and services by using docker init to create your Dockerfile and associated resources. This saves time and improves consistency across your project inventory.
• Add Docker to existing projects, with sensible defaults: docker init configures older projects for Docker even when they span several languages, and it applies the same defaults every time.
• Learn how to use Docker with additional programming languages: Perhaps you’re already comfortable writing Dockerfiles for Python apps, but what if you’re now tasked with launching a Go service? Inspecting the output of docker init is a quick way to learn the basics of how to Dockerize apps written in any of the languages that the tool supports.
• Save time and automate more project management tasks: You will still edit the files it creates, but starting from something that runs beats assembling a Docker configuration from scratch on every repository.

Now let’s look at an example of how to use Docker init to containerize a simple application.

We’ll use docker init to containerize a Node.js project. You need Docker Desktop and Node.js installed to follow along.

1. Confirm you have Docker Desktop

docker init is a Docker CLI plugin that ships with Docker Desktop 4.18 and later. Run docker init --version to confirm it is available.

2. Create a minimal Node.js app

To begin, navigate to a new directory for the files you’ll create in this guide. Then, copy the following Node.js app and save it as main.js in your directory:

const express = require("express");

const app = express();

app.get("/", (req, res) => {
	res.send("Node.js demo app using Express.");
});

app.listen(3000, () => {
	console.log("App is listening.");
});

The app starts an Express web server on port 3000. It serves a single route (/) that sends a basic message in its response.

Initialize the project so docker init can detect it as a Node app, then install Express:

$ npm install express

Now you’re ready to containerize your app.

3. Run docker init

docker init is interactive and takes no flags apart from --version. Run it in your working directory and it prints some help text, then asks which application platform you use:

$ docker init

Welcome to the Docker Init CLI!

This utility will walk you through creating the following files with sensible defaults for your project:
  - .dockerignore
  - Dockerfile
  - compose.yaml
  - README.Docker.md

Let's get started!

? What application platform does your project use?  [Use arrows to move, type to filter]
> Node - (detected) suitable for a Node server application
  Go - suitable for a Go server application
  Java - suitable for a Java application that uses Maven and packages as an uber jar
  Python - suitable for a Python server application
  Rust - suitable for a Rust server application
  ASP.NET Core - suitable for an ASP.NET Core application
  PHP with Apache - suitable for a PHP web application
  Other - general purpose starting point for containerizing your application
  Don't see something you need? Let us know!
  Quit

You can see that the Node project type has been automatically detected for our sample app. Press the enter key to accept it.

Next, you’ll be asked which version of Node.js you’re using:

? What version of Node do you want to use? (24.4.1)

The default matches the Node.js version detected on your machine, 24.4.1 in this case. Press enter to accept it or type a different version number. If you specify a particular version, it must have a matching Docker image available on Docker Hub.

Next, you’ll be asked to identify the package manager you’re using—npm should be auto-detected so you can immediately press enter to continue:

? Which package manager do you want to use?  [Use arrows to move, type to filter]
> npm - (detected)
  yarn
  pnpm

Next, docker init asks whether your project needs a build step, and where the build output goes. This sample app has no build step, so answer No:

? Do you want to run "npm run build" before starting your server? No

The next prompt requires you to enter the command that will be used to run your app when containers start:

? What command do you want to use to start the app? [tab for suggestions]

For this tutorial, the sample code is saved as main.js so you should use node main.js as your command. This will run your application using the node binary found in the container and your main.js source code. The docker-init-generated Dockerfile automatically copies your source into the container’s working directory.

Finally, you need to tell Docker what port your app is configured to listen on. This is 3000 in this tutorial.

? What port does your server listen on?

docker init then confirms the four files it created:

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:3000

Consult README.Docker.md for more information about using the generated files.

4. Run your app

Now run your app with Docker.

It’s easiest to use Docker Compose to both build your image, then start a container in a single command:

$ docker compose up --build
[+] Building 50.1s (13/13)	FINISHED                        docker:default
(truncated)
[+] Running 2/2
 ✔ Network spl-docker-init_default     Created             0.2s
 ✔ Container spl-docker-init-server-1  Created             0.3s
Attaching to spl-docker-init-server-1
spl-docker-init-server-1  | App is listening.

You’ll see verbose logs in your terminal as Docker builds your image’s filesystem layers; it’ll then create your container and attach it to its foreground process so you can see your app’s logs.

Now you should be able to reach the app at localhost:3000:

$ curl http://localhost:3000
Node.js demo app using Express.

That’s it. You generated the Docker config files, built your image, and ran your app.

How to containerize other types of applications?

It’s best to use the language-specific template provided by docker init when possible. If your app isn’t supported, or you want a less guided experience, select the “Other” template at the first prompt.

“Other” writes minimal Dockerfile, compose.yaml, .dockerignore, and README.Docker.md files ready for you to customize. They’re a good way to familiarize yourself with Docker basics and best practices because the generated output is well-documented and includes tips, explanations, and optional capabilities you can enable by uncommenting sections of the files. For example, there’s a ready-to-use example of how to deploy a PostgreSQL database connection alongside your app available in the default compose.yaml.

Docker Desktop now ships two ways to generate Docker assets, and they suit different jobs.

docker init works from fixed templates. The output is predictable, so every project in your organization starts from the same Dockerfile shape, and you can review a template once and trust it everywhere. It covers seven languages and nothing else.

Gordon, Docker’s AI assistant, reads your actual project. Run docker ai in your terminal or open Gordon from the Docker Desktop sidebar, and it can write a Dockerfile and Compose file for frameworks and multi-service setups no template covers, then optimize what it wrote. It proposes each action and waits for your approval. The tradeoff is that the output varies between runs.

Reach for docker init when you want consistency across repositories. Reach for Gordon when your project falls outside the templates, or when you want an existing Dockerfile improved rather than created.

docker init is a simple command, but five things are worth keeping in mind.

1. Provide accurate answers to the docker init prompts

Answer every prompt accurately when you use a language-specific template. Wrong answers produce a configuration that doesn’t match your project, and you find out when the build or the container fails.

2. Analyze whether the default base image is suitable for your app

docker init picks a base image from your answers. Check that it fits: the Node template uses Alpine images, and your project might need a Debian environment or a hardened image instead. Change it by editing the FROM instruction near the top of the generated Dockerfile.

3. Customize generated files after creation to match your use case

docker init gives you a starting point, not a finished setup. Customize the generated files if your app has additional requirements, such as other containerized services that belong in your Compose project.

4. Back up existing files before you overwrite them

docker init works on existing projects, which makes it a fast way to add Docker support. Take care if someone has already added it. If any of the four files exist, docker init warns you and offers to overwrite all of them rather than letting you pick file by file, and overwritten files cannot be recovered. 

Rename or copy anything you want to keep before you run the command. One quirk worth knowing: if the project has a docker-compose.yaml instead of a compose.yaml, docker init can overwrite it and keep the existing filename.

5. Make sure your team knows what docker init does

docker init introduces new engineers to Docker without making them learn the whole image authoring workflow first. Make sure they know what it actually does, which is write language-specific templates, so nobody treats the output as production-ready by default.

These points will ensure you can utilize Docker Init without encountering issues in the future.

In this article, we’ve looked at how Docker init lets you automate initial Docker configuration in your projects. It writes a Dockerfile, compose.yaml, and .dockerignore for you, lowering the learning curve and accelerating setup time. Note that while we’ve focused on using Docker Init with Node.js, the interactive prompt steps are similar for the other supported programming languages too.

Docker Init is a convenient tool but its output won’t always be suitable to use as-is. More advanced projects will still require customization of your Dockerfile, such as to install any extra dependencies you require, or to make changes to the base image that’s used. Similarly, you may have to modify your Docker Compose compose.yaml file to add any extra services that you require.

For more Docker material, see the Docker cheat sheet for CLI commands and the rest of the Docker content on the Spacelift blog.

docker init gets one project containerized. Keeping every project’s image consistent once those projects reach your pipeline is a different problem. Spacelift lets you bring your own Docker image and use it as a runner, so the tools your stacks depend on are pinned in an image you control instead of installed at run time. Spacelift’s official runner image is on GitHub.

We encourage you also to explore how Spacelift offers full flexibility when it comes to customizing your workflow. You have the possibility of bringing your own Docker image and using it as a runner to speed up the deployments that leverage third party tools. Spacelift’s official runner image can be found here.