Skip to main content
Gå til innhold

Local development using Docker

Before you deploy your web site to the PaaS, you should first build and test it locally using Docker. This allows you to verify that the application works before you try to bring it up on the PaaS.

Terminology​

Before you begin, it can be useful to clarify some terms that we will use through this document:

  • Container image: A self contained bundle with an application and all its dependencies. In this case it will be your web site combined with the web server and all dependencies the web server requires.
  • Container: A running copy of a container image.
  • Docker: Docker is a software suite for building and running container images.

Creating the project directory and web site​

The first step is to create an empty directory for your web site. Create an empty directory by running mkdir my-web-site and then switch to it by running cd my-web-site. When you have done that, you should be able to run ls -a and only see entries for the current directoy and parent directory (. and ..):

$ mkdir my-web-site
$ cd my-web-site
$ ls
.  ..

Next you will need to add a HTML file with the web site. Create a file named index.html containing something like <h1>Hello World!</h1>.

You can then verify that the file was created correctly by running ls -a and cat index.html:

$ echo '<h1>Hello World!</h1>' >index.html
$ ls -a
.  ..  index.html
$ cat index.html
<h1>Hello World!</h1>

Dockerfile​

You are going to build a container image with your web site. This image contains both your web site and all its dependencies (i.e. the web server and required libraries).

Here we will use Nginx as the web server. Docker provides an official image for Nginx at Dockerhub. You are going to combine that image with your index.html file to create a new container image.

To build a container image you will need to create a file named Dockerfile. This file contains build instructions for our container image. The file contains a series of lines, each of which is a step for building the image.

Create a file named Dockerfile in the current directory with the following contents:

FROM nginx
COPY index.html /usr/share/nginx/html/

Here you have two commands:

  • FROM nginx: Start with the existing nginx image from Dockerhub.
  • COPY index.html /usr/share/nginx/html/: Copy index.html in the current directory to /usr/share/nginx/html/ in the container. (The nginx image looks for web content in /usr/share/nginx/html by default -- see the Nginx Docker documentation for more details.)

See the Dockerfile reference for more information about the contents of Dockerfile.

Once you have created the file, you can verify the result using ls -a and cat Dockerfile:

$ ls -a
.  ..  Dockerfile  index.html
$ cat Dockerfile
FROM nginx
COPY index.html /usr/share/nginx/html/

Building the image​

Now that you have a Dockerfile with build instructions, you can use docker build to build our Docker image:

docker build -t my-web-site-image .

This command consists of three parts:

  • docker build: This invokes the build-subcommand of docker. This is the command that creates container images.
  • -t my-web-site-image: This names the created container image my-web-site-image, which makes it easier to refer to the image afterwards.
  • .: This is a reference to the directory containing the Dockerfile. In this case, you build the image from the current working directory (.).

When running the command you should get output similar to:

$ docker build -t my-web-site-image .
Sending build context to Docker daemon  3.072kB
Step 1/2 : FROM nginx
latest: Pulling from library/nginx
Digest: sha256:10b8cc432d56da8b61b070f4c7d2543a9ed17c2b23010b43af434fd40e2ca4aa
Status: Downloaded newer image for nginx:latest
 ---> f6d0b4767a6c
Step 2/2 : COPY index.html /usr/share/nginx/html/
 ---> 8ed1245eacb3
Successfully built 8ed1245eacb3
Successfully tagged my-web-site-image:latest

Running the image​

You now have a Docker image named my-web-site-image. You can run that image using docker run:

docker run --rm -ti -p 8080:80 my-web-site-image

This command consists of five parts:

  • docker run: This invokes the run-subcommand of docker. This is the command that runs Docker images.
  • --rm: By default Docker keeps old containers around after they exit, allowing you to examine their state (e.g. logs) after they have exited. The --rm flag instructs Docker to clean up the container automatically when it exits.
  • -ti: By default, Docker launches containers without allowing you to interact with them. Add the -ti flags (short for --tty and --interactive) to allow you to see their output in the terminal and send keypressses to the container.
  • -p 8080:80: Each container runs in its own isolated network environment. In order to access services in the container you need to configure a port forwarding rule. Nginx in the container listens on port 80 by default. Here you configure a port forwarding from port 8080 on the host to port 80 in the container. This allows the container to be accessed on http://localhost:8080/.
  • my-web-site-image: This is the name of the container image that you want to run. This matches the -t my-web-site-image parameter to docker build.

When you run the docker run command, you should get output like:

$ docker run --rm -ti -p 8080:80 my-web-site-image
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Configuration complete; ready for start up

The web site should then be running and waiting for you to access it.

Accessing the web site​

Once the container is running, you can access the web site on http://localhost:8080/.

When you access the site, you should also receive additional output from the docker run command. This output is log messages from the Nginx web server in our container.

Stopping the container​

When you are done testing your site, you can stop the container by pressing Ctrl+C. This should cause the container to exit.