Complete Guide to Passing Arguments to CMD in Docker via Environment Variables

Core Mechanisms of Parameter Passing in Docker

In the Docker ecosystem, passing parameters to applications running inside containers is a common requirement. Many applications need to receive configuration parameters at startup, such as Node.js applications that may require specifying runtime mode (development/production) and cluster configuration. Docker provides multiple mechanisms to achieve this goal, with passing parameters through environment variables being one of the most flexible and recommended methods.

Definition and Usage of Environment Variables in Docker

The ENV instruction in Dockerfiles is used to define environment variables, which can be utilized during both the build and runtime phases. There are two syntax forms for environment variable definition: ENV key value and ENV key=value. Environment variables defined in Dockerfiles persist in the generated images, becoming the default environment configuration for containers.

FROM node:14
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
ENV ENVIRONMENT=dev
ENV CLUSTER=0
CMD ["node", "server.js"]

Runtime Environment Variable Override Mechanism

Using the -e option of the docker run command allows overriding or adding environment variables when containers start. This mechanism enables dynamic adjustment of application configuration parameters without modifying Dockerfiles or rebuilding images. For example, to switch an application to production mode and enable cluster functionality, execute:

docker run -p 9000:9000 -e ENVIRONMENT=prod -e CLUSTER=1 -d me/app

CMD Instruction Forms and Environment Variable Expansion

The CMD instruction in Dockerfiles has two forms: shell form and exec form. Understanding the difference between these two forms is crucial for correctly using environment variables.

Shell Form CMD

The shell form CMD instruction executes commands through a shell process, thus supporting environment variable expansion and shell features. The syntax is as follows:

CMD node server.js $CLUSTER $ENVIRONMENT

The advantage of this form is simplicity and intuitiveness, with automatic environment variable expansion. However, it has an important drawback: the started process is not the container's PID 1 process but a child process of the shell. This may cause issues with signal delivery and process management.

Exec Form CMD

The exec form CMD instruction uses JSON array syntax to directly execute specified commands without going through a shell process. The syntax is as follows:

CMD ["node", "server.js", "0", "dev"]

The advantage of this form is that the started process directly becomes the container's PID 1 process, providing more reliable signal handling. The disadvantage is that environment variables are not automatically expanded. To address this, shell must be explicitly invoked to handle environment variable expansion:

CMD ["sh", "-c", "node server.js ${CLUSTER} ${ENVIRONMENT}"]

This hybrid approach combines the signal handling advantages of the exec form with the environment variable expansion capabilities of the shell form. It's important to note that although the command is executed through shell, environment variable expansion is performed by the shell itself, not by Docker.

Environment Variable Configuration in Docker Compose

In Docker Compose configuration files, environment variables can be set through the environment field. This approach is particularly suitable for configuration management in multi-container applications:

version: '3'
services:
  app:
    build: .
    ports:
      - "9000:9000"
    environment:
      - ENVIRONMENT=dev
      - CLUSTER=0

Alternative Approach Using ENTRYPOINT and CMD

Another common parameter passing pattern involves using a combination of ENTRYPOINT and CMD. ENTRYPOINT specifies the command that always executes when the container starts, while CMD provides default arguments. This pattern allows directly passing parameters when running containers without needing environment variables:

FROM node:14
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
ENTRYPOINT ["node", "server.js"]
CMD ["0", "dev"]

When running containers, parameters can be directly passed:

docker run -p 9000:9000 -d me/app 1 prod

The advantage of this method is more intuitive parameter passing without dealing with the complexity of environment variable expansion. The disadvantage is slightly reduced flexibility, as parameters must be passed in a specific order and cannot be configured in batches through environment files.

Best Practice Recommendations

Based on practical application scenarios, here are some best practice recommendations:

1. Sensitive Information Handling: For sensitive information like passwords and API keys, use Docker Secrets or load from external files via the --env-file option to avoid direct exposure in command lines.
2. Default Value Setting: Set reasonable default values for all environment variables in Dockerfiles to ensure containers can run properly without external configuration.
3. Configuration Validation: Validate environment variable validity during application startup, providing clear error messages for easier troubleshooting.
4. Documentation: Clearly document all available environment variables and their purposes in project documentation to facilitate usage by other developers.
5. Testing Strategy: Write test cases for different environment variable combinations to ensure configuration changes don't break application functionality.

Practical Application Example

The following is a complete Node.js application example demonstrating how to implement flexible parameter passing in Docker:

// server.js
const cluster = process.env.CLUSTER === '1';
const environment = process.env.ENVIRONMENT || 'dev';

if (cluster) {
  console.log('Running in cluster mode');
  // Cluster initialization logic
}

console.log(`Starting server in ${environment} mode`);
// Server startup logic

// Dockerfile
FROM node:14-alpine
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV ENVIRONMENT=dev
ENV CLUSTER=0
EXPOSE 9000
CMD ["sh", "-c", "node server.js ${CLUSTER} ${ENVIRONMENT}"]

Through this approach, developers can easily switch between different environments without modifying code or rebuilding Docker images, significantly improving development and deployment efficiency.