How to create local Docker image

In this article, we explain how to build a local Docker image from scratch, why it is essential to understand this process, and how it can save you time and headaches in your future projects.

Creating a local Docker image is one of the key first steps for any developer who wants to take advantage of the isolated, scalable, and replicable environments this technology offers. If you're just starting out with Docker, you've likely already run a few containers with existing images from Docker Hub. However, in real-world development, what you'll most likely need is to create your own images, tailored exactly to your needs.

What is a Docker image?

Before getting into the details, it's worth clarifying what a Docker image is. A Docker image is an immutable template that contains everything needed to run an application: the base operating system, dependencies, binaries, libraries, environment variables, and any custom settings. Images are the foundation on which containers are built.

Think of an image as a recipe, and the container as the prepared dish. If you want that dish to taste exactly the way you want it, you need to define the recipe well.

Why create a local image?

Although you can download pre-built images from Docker Hub, they often don't fit your application's needs. Creating a local image allows you to:

• Completely customize the runtime environment.
• Verify your environments just like your source code.
• Remove unnecessary external dependencies.
• Optimize the performance of your containers.
• Ensure consistency between development, testing, and production environments.

In addition, from an organizational perspective, having control over your images improves traceability, facilitates security audits, and gives you independence from public repositories.

Step 1: Create a Dockerfile

It all starts with a file called Dockerfile. This file defines, step by step, how your image is built.

Here's a basic example for a Node.js application:

# Official Node.js base image
FROM node:18

# Set the working directory
WORKDIR /app

# Copy the project files
COPY package*.json ./
RUN npm install

COPY . .

# Expose the port on which the app will run
EXPOSE 3000

# Default command when starting the container
CMD ["node", "index.js"]

This Dockerfile tells Docker to use the official Node.js image as a base, copy your project files, install dependencies, expose a port, and run the application.

Step 2: Build the image with Docker build

With your Dockerfile ready, navigate to the folder where it's located and run:

docker build -t my-local-app .

This command tells Docker to build an image named my-local-app using the context of the current directory.

During this process, Docker will execute each instruction in the Dockerfile and generate a local image that you can reuse as many times as you need.

Pro tip: Make sure to use tags to identify versions, such as my-local-app:v1.0.

Step 3: Verify that the image exists

Once the build is complete, you can list your local images with:

docker images

You'll see something like this:

REPOSITORY    TAG      IMAGE ID    CREATED       SIZE
my-local-app latest 7e2f5abf9b2b 10 seconds ago 145MB

This confirms that your image is ready to use.

Step 4: Run your container

Finally, you can run a container based on your local image:

docker run -p 3000:3000 my-local-app

This command runs your container and exposes port 3000 on your local machine so you can access the application from a browser.

Best Practices for Creating Docker Images

Creating efficient images isn't just about making them work. They must also be fast, secure, and easy to maintain. Here are some tips:

• Minimize layers: Each instruction in the Dockerfile creates a new layer. Combine commands where it makes sense.
• Avoid unnecessary files: Use .dockerignore to exclude files that shouldn't be in the image (such as node_modules, .git, etc.).
• Use small base images: Images like alpine are lightweight and reduce the final size of your image.
• Tag your images with clear versions: This improves traceability and maintenance.
•  

Automation and Deployment

Once you've mastered this manual process, you can integrate it into your CI/CD workflow with tools like GitHub Actions, GitLab CI, or Jenkins. In fact, many organizations automate the creation and publication of images to private repositories like Docker Hub, AWS ECR, or GitLab Registry, making deployment to any environment easy.

According to a Datadog study, more than 80% of container developers work with custom images in their daily workflow, demonstrating the strategic importance of mastering this skill.

What if you need help?

While creating a local Docker image is relatively simple, maintaining an ecosystem of optimized, secure, and automated images can quickly escalate in complexity. At Rootstack, we've helped companies of all sizes implement container-based infrastructures, designing custom images that precisely fit each project's requirements.

Creating a local Docker image is not only an essential skill for modern developers, but also the starting point for achieving efficient and reproducible workflows. Learning how to do it well is an investment that pays dividends in every sprint.

We recommend you on video