Skip to main content

Creating a parameterized Dockerfile

Overview​

Using parameters in a Dockerfile allows you to create flexible and reusable images that can adapt to different environments or use cases. This article explains how to use parameters to modify an application’s behavior, explores the distinction between build-time and run-time parameters, and includes a practical example to demonstrate these concepts.

Videotutorial​

See also...

Watch this tutorial on Parametrized Dockerfiles.

Understanding Parameters in a Dockerfile​

Parameters in a Dockerfile enable developers to define values that can be adjusted during the image build or container runtime. These parameters are specified using:

  • Build-time parameters: Defined using ARG in the Dockerfile. These are set during the image build process.
  • Run-time parameters: Defined using ENV in the Dockerfile. These are set as environment variables inside the container and can be overridden when the container is started.

Build-Time vs. Run-Time Parameters​

Build-Time Parameters​

Build-time parameters define variables that influence the image creation process. They are typically used for:

  • Specifying dependencies or configurations required at build time.
  • Passing secrets or temporary values during the build process.

Example:

ARG NODE_VERSION=14
FROM node:${NODE_VERSION}

Here, NODE_VERSION determines which version of Node.js is used as the base image.

Run-Time Parameters​

Run-time parameters define environment variables that affect the container’s behavior after it has been built and is running. They are useful for:

  • Configuring the application’s runtime behavior.
  • Setting application secrets or environment-specific values.

Example:

ENV APP_ENV=production

Here, APP_ENV specifies whether the application runs in production or development mode.

Creating a Parameterized Dockerfile​

In this example, we’ll create a Node.js application Dockerfile that:

  • Uses ARG to specify the Node.js version at build time.
  • Uses ENV to set the application mode (production or development) at runtime.

Modifying Parameters Using the docker Command​

You can customize parameters during the image build and container runtime using the docker build and docker run commands.

  • Modify Build-Time Parameters (ARG): Use the --build-arg flag with docker build to pass a value for an ARG parameter defined in the Dockerfile.

    Example:

    docker build -t parameterized-app:1.0 --build-arg NODE_VERSION=16 .

    Here, NODE_VERSION is set to 16, overriding the default value (14) specified in the Dockerfile.

  • Modify Run-Time Parameters (ENV): Use the -e flag with docker run to pass an environment variable to the container.

    Example:

    docker run -p 8080:8080 -e APP_MODE=development parameterized-app:1.0

    Here, APP_MODE is set to development, overriding the default value (production).

Hands-On Practice​

Step 1: Create a Project Directory​

mkdir 03_01_parameterized-dockerfile
cd 03_01_parameterized-dockerfile

Step 2: Create the Application Files​

app.js:​

const http = require('http');
const appMode = process.env.APP_MODE || 'development';

const server = http.createServer((req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Application is running in ${appMode} mode!\n`);
});

server.listen(8080, () => {
    console.log(`Server running on http://localhost:8080 in ${appMode} mode.`);
});

package.json:​

{
  "name": "parameterized-dockerfile",
  "version": "1.0.0",
  "main": "app.js",
  "dependencies": {
    "http": "^0.0.1-security"
  }
}

Step 3: Create the Dockerfile​

Dockerfile:​

# Define build-time argument for Node.js version
ARG NODE_VERSION=14

# Use the specified Node.js version as the base image
FROM node:${NODE_VERSION}

# Set the working directory
WORKDIR /app

# Copy application files
COPY package*.json .
COPY app.js .

# Install dependencies
RUN npm install

# Set runtime environment variable
ENV APP_MODE=production

# Expose the application port
EXPOSE 8080

# Define the default command
CMD ["node", "app.js"]

Step 4: Build and Run the Docker Image​

  • Build the image with a custom Node.js version:

    docker build -t parameterized-app:1.0 --build-arg NODE_VERSION=16 .

  • Run the container with a custom environment variable:

    docker run -p 8080:8080 -e APP_MODE=development parameterized-app:1.0

Step 5: Test the Application​

Use curl or open a browser to access the application:

curl http://localhost:8080

Expected output:

Application is running in development mode!

Summary​

Using ARG and ENV in Dockerfiles enables flexible and reusable images that can adapt to various scenarios. ARG is ideal for setting values at build time, such as the base image version, while ENV allows for configuration at runtime, such as setting application modes. By combining these features, developers can create versatile Docker images suitable for diverse deployment requirements.