Updated March 28, 2023
Introduction to Docker WORKDIR
Docker WORKDIR is a Dockerfile instruction that is used to set the working directory for any of the instructions like RUN, CMD, ENTRYPOINT, COPY and ADD, which means any command mentioned after these instructions will be executed in the working directory that is specified using WORKDIR instruction in the Dockerfile. It also sets the working directory of a Docker container, which means if we have specified any path using WORKDIR and when we connect the container using the ‘exec’ command, then it will directory land us to that directory. Docker daemon creates the folder if the specified directory does not exist.
Syntax:
WORKDIR <Directory_Path>
WORKDIR <Directory_Name>
- Directory_Path: We can provide an absolute path at the top; else, it will be created under the ‘/.’
- Directory_Name: We can only provide the directory name as well.
How does WORKDIR Command work in Docker?
As seen, WORKDIR instruction is used to set the current working directory for the container so that subsequent instructions like RUN, CMD, ENTRYPOINT, etc., do not require to give the absolute path as it executes the command in the working directory that WORKDIR specifies. Therefore, we can use WORKDIR instruction multiple times, and if the relative path is provided in the further WORKDIR instruction, then it will be related to the previous WORKDIR instruction.
Example:
WORKDIR /home
WORKDIR my_home
WORKDIR Desktop
RUN pwd
If we create an image using the above Dockerfile and run it, then it will output the present working directory, i.e.,/home/my_home/Desktop.
We can also use the environment variables in WORKDIR instruction if any environment variable is defined in the Dockerfile previously using ENV instruction. However, we can only use the environment variable defined explicitly in the Dockerfile, which means the environment variable we want to use in the WORKDIR instruction must be set in the same Dockerfile prior to use it.
Examples of Docker WORKDIR
Given below are the examples of Docker WORKDIR:
Example #1
Create a Docker image with single WORKDIR instruction.
a. Create a Dockerfile and populate it with the below data:
$vi Dockerfile
FROM ubuntu
WORKDIR /var/www/html
RUN apt-get update && apt-get install -y nginx
COPY index.html .
ENTRYPOINT ["nginx", "-g", "daemon off;"]
b. Create an index.html file and populate it with some HTML code as shown below:
$vi index.html
<!DOCTYPE html>
<html>
<body>
<p>Testing WORKDIR instruction</p>
</body>
</html>
c. Build a new image using Dockerfile mentioned in step 1:
docker build -t my-nginx .
Output:
Explanation:
In the above snapshot, the below steps are taken by the Docker daemon.
- Step 1/5: Docker daemon creates a container using the ‘Ubuntu’ docker image in the first step.
- Step 2/5: The second step changes the directory to ‘/var/www/html.’
- Step 3/5: It updates the system and installs nginx in the intermediate container.
- Step 4/5: Now, it copies the index.html that is created in step 2 above to the current working directory, i.e. ‘/var/www/html’ as we have defined this path using the ‘WORKDIR’ instruction in step 2 in Dockerfile.
- Step 5/5: It defines the default command to run whenever the container is created.
d. Now, we can create a container using the newly created image and connect to it to verify everything is as expected:
docker run -d --name my-container my-nginx
docker exec -it my-container sh
# pwd
/var/www/html
# cat index.html
Output:
Explanation:
- In the above snapshot, we can see that we directly landed on the working directory, which WORKDIR set, and when we checked the content of index.html, it is the same file we have copied.
Example #2
Create a Docker image with multiple WORKDIR instructions in the Dockerfile.
a. Here is the Dockerfile for the same.
$vi Dockerfile
FROM alpine
WORKDIR /home
WORKDIR my_home
WORKDIR Desktop
RUN pwd
b. Let’s build a Docker image using the above Dockerfile.
docker build –t multi-workdir .
Output:
Explanation:
- In the above snapshot, we can see that in step 5/5, the Docker daemon output the present working directory, and that is ‘/home/my_home/Desktop.’ So it looks like changing the directory.
c. Just to cross-check, we can create a container using this Docker image and connect to it as below:
docker run -d --name my-cont multi-workdir sleep 3600
docker exec -it my-cont sh
Output:
Explanation:
- The above snapshot shows that the current working directory is the same as mentioned above.
Example #3
Use environment variable in WORKDIR instruction.
a. Here is the Dockerfile for the same:
$vi Dockerfile
FROM alpine
ENV DIRPATH /home/my_home
WORKDIR $DIRPATH/Desktop
RUN pwd
b. Let’s build a new Docker image using the above Dockerfile:
docker build -t env-workdir .
Output:
Explanation:
- In the above snapshot, the Docker daemon sets the environment variable ‘DIRPATH’ to ‘/home/my_home’ in step 2/4. It replaces the environment variable in the next step with it when we have used it in WORKDIR instruction. When we check the current working directory in the last step, we can see that it has set the working directory as expected.
Advantages of Docker WORKDIR
Given below are the advantages mentioned:
- First, it saves our time to write the full path repeatedly in the Dockerfile.
- Second, it makes us understand the Dockerfile easily by removing the mess of long paths.
- Third, it improves the clarity and readability of the Dockerfile.
Rules and Regulations for Using a WORKDIR
Given below are the rules and regulations mentioned:
- We should use an absolute path while defining WORKDIR instruction for reliability.
- We can only use the environment variables that are defined in the same Dockerfile.
- ENV must be defined in the Dockerfile before using it in the WORKDIR instruction.
Conclusion
The ‘WORKDIR’ instruction is very useful instruction to remove the clutter from RUN, CMD, ENTRYPOINT, etc., instructions in which we need to define the path. Therefore, it is recommended to use WORKDIR in the Dockerfile.
Recommended Articles
This is a guide to Docker WORKDIR. Here we discuss the introduction, how the WORKDIR command works in docker? Examples, advantages, rules, and regulations. You may also have a look at the following articles to learn more –
