Setting up Docker for a new project usually starts the same way: you Google a template, paste it in, change a couple of lines, and hope for the best. The build fails, so you tweak and repeat until it works. Every new project begins with a blank Dockerfile and a vague memory of what worked last time.
The docker init command fixes this. It is a single CLI command that detects what language or framework your project uses, asks a few questions, and generates three files: a Dockerfile, a .dockerignore, and a compose.yaml. All three follow Docker’s current best practices, which means you start from a solid baseline instead of a Stack Overflow relic from 2019.
What Docker Init Generates
When you run docker init in your project directory, it scans for language-specific files to determine your stack. A requirements.txt means Python. A package.json means Node.js. It also supports Go, Java, and .NET. If it cannot detect your stack automatically, you can select one from the prompt. The detection is fast — it looks at a handful of well-known filenames rather than trying to parse your entire project structure.
After detection, the command asks a few interactive questions: what port your application listens on, what command starts it, and whether you want to include a database service. Based on your answers, it writes three files to your project folder:
my-project/
├── Dockerfile
├── .dockerignore
└── compose.yamlThe Dockerfile uses multi-stage builds where appropriate, pins base image versions, and includes comments explaining each instruction. The .dockerignore excludes files that bloat the build context — node_modules, .git, pycache, and similar directories. The compose.yaml defines your service with sensible defaults, including a health check and volume mounts for development.
These are not read-only templates. The generated files are meant to be edited. Review them, tweak the build steps, lock down your base image version, and add your environment variables. The more your project grows, the more you will diverge from the defaults — but the defaults give you something correct to diverge from.
Step-by-Step: Using Docker Init
Navigate to your project directory and run the command:
cd my-project
docker initThe command detects your stack and presents the first prompt. For a Python project, it might look like:
? What version of Python do you want to use? (3.11.4)
? What port does your server listen on? (8000)
? What is the command to run your app? (python -m uvicorn main:app --host 0.0.0.0)Accept the defaults by pressing Enter, or type your own values. The detected defaults are usually correct for standard project structures.
After answering the prompts, docker init writes the three files. Open each one and read through the comments. The Dockerfile, in particular, explains why each instruction is there, which is worth a few minutes even if you plan to modify it.
Build and start your container with:
docker compose up --buildThe --build flag tells Docker to build the image from your Dockerfile before starting the container. Your application should be accessible on the port you specified.
Working With Existing Projects
docker init is not limited to new projects. You can run it in any project folder, even one that already has Docker configuration files. If a Dockerfile or compose.yaml already exists, the command warns you before overwriting.
This is useful for replacing outdated or poorly written Dockerfiles. Many projects carry Docker configurations that were copied from tutorials years ago and never updated. Running docker init in those projects generates a fresh baseline with current best practices — multi-stage builds, proper .dockerignore rules, and Compose health checks — that you can then customize.
The command does not manage your containers or handle deployment. It is a scaffolding tool that gets your configuration started so you can focus on the actual work. For production deployment, you will still need to add registry push steps, environment-specific overrides, and resource limits.
Limitations You Should Know About
Docker init generates single-stage Dockerfiles by default. If you need multi-stage builds — compiling in one stage and running in another to minimize image size — you will need to write that manually. The generated Dockerfile is a starting point, not a production-optimized final form.
The command also does not support advanced build patterns. Custom base images, build arguments with conditional logic, and specialized caching strategies are outside its scope. If your project requires any of that, you are writing the Dockerfile yourself anyway, and that is fine.
The generated Compose file covers common service patterns well, but it is still a template. Projects with unusual directory structures, custom networking requirements, or specialized database configurations will need manual adjustments. The template gives you the structure; you provide the specifics.
None of this makes docker init a bad tool. It means you should go in with the right expectations: it removes the blank-page problem, but it does not replace the need to understand what is in your Dockerfile.
Best Practices After Using Docker Init
The files docker init generates are a starting point. Here are the steps to turn them into something production-ready:
Pin your base image version. The generated Dockerfile uses a specific Python or Node version, but you should verify it matches what your production environment runs. A mismatch between local and production base images is a common source of “works on my machine” bugs.
Add environment variables. The generated Dockerfile does not include your database URLs, API keys, or other secrets. Add them as environment variables in your Compose file, and use Docker secrets or a .env file for sensitive values — never hardcode them in the Dockerfile.
Configure health checks. The Compose file includes a basic health check, but you should customize it for your application. A web server health check is different from a background worker health check, and the default might not accurately reflect whether your service is actually ready to handle requests.
Set resource limits. The generated Compose file does not include CPU or memory limits. In production, a container without resource limits can consume all available resources and starve other services. Add deploy.resources.limits to your Compose file to prevent this.
Review the .dockerignore. The generated .dockerignore excludes common directories, but your project might have large files or directories that should not be in the build context. Check what is being sent to the Docker daemon and exclude anything that is not needed for the build.
Test the build. Run docker compose up --build and verify that your application starts correctly. Check the logs for warnings or errors. Test the health check. Make sure the port mapping works. The generated files are correct in structure, but only you know if they are correct for your specific application.
Docker Init vs. Manual Setup
Writing your Dockerfile by hand gives you full control over every layer, every instruction, and every build decision. You can implement multi-stage builds to minimize image size, use custom base images, or fine-tune caching behavior in ways that docker init cannot anticipate.
But manual setup also means you are responsible for getting everything right. The non-root user, the .dockerignore rules, the layer ordering for cache efficiency — these details are easy to miss when you are writing from scratch. Docker init handles them automatically, which is valuable even if you end up modifying most of the output.
The practical approach is to use docker init as your starting point, then evolve the generated files as your project grows. Start with the defaults, get your application running, and then optimize. The generated Dockerfile is not the end of the process — it is the beginning.
What the Generated Dockerfile Looks Like
For a Python Flask application, docker init might generate something close to this:
# syntax=docker/dockerfile:1
ARG PYTHON_VERSION=3.11.4
FROM python:${PYTHON_VERSION}-slim AS base
# Prevent Python from writing .pyc files and enable unbuffered output
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app
# Create a non-root user
RUN addgroup --system appuser && adduser --system --ingroup appuser appuser
# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application code
COPY . .
# Switch to non-root user
USER appuser
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]The key details: it uses a slim base image to keep the final image small, creates a non-root user for security, separates dependency installation from code copying for better layer caching, and disables .pyc file generation. These are the kinds of details that most copy-pasted Dockerfiles miss.
When to Use Docker Init vs. Writing Your Own
Docker init works best for standard application stacks — Python web services, Node.js APIs, Go binaries, Java applications. If your project fits one of these patterns, the command saves time and produces correct output.
For more complex setups — multi-service architectures with databases, message queues, and custom networking — you will still need to extend the generated files. The Compose file from docker init gives you a starting point, but production deployments typically need additional services, volume configurations, and environment-specific overrides.
For projects with unusual requirements — custom build processes, non-standard directory structures, or specialized base images — writing your Dockerfile from scratch may be faster than modifying the generated one. The command is a starting point, not a constraint.
The real value of docker init is not the files themselves. It is the baseline of correctness they provide. Even if you end up rewriting most of the Dockerfile, starting from a configuration that follows current best practices is better than starting from a blank file and hoping you remember the right syntax for multi-stage builds. The command does the boring part — .dockerignore rules, non-root user setup, layer ordering — so you can focus on the interesting part: building your application.
