Docker Reference Guide

Running Pangeo Base Image:

docker run -it --privileged \
      --rm -p 8080:8888 \
        -p 8081:8787 \
        -v "${PWD}":/home/jovyan/work \
        -v $HOME/.aws/:/home/jovyan/.aws/ \
        -e GRANT_SUDO=yes \
        pangeo/pangeo-notebook:latest \
        jupyter lab --ip 0.0.0.0 --NotebookApp.token=''

Writing A Dockerfile

Helpful Base Images:

Basic Template

Replace bracketed text below.

# Start with a base image
FROM [base-image]

#  Run any configuration commands
RUN 

# Set any environmental variables
ENV PATH="/root/.cargo/bin:${PATH}"

# Copy any required files and/or directories
# into the image
COPY 

# Run any additional commands
# (Install environment?)
RUN 

CMD [Run your script]
ENTRYPOINT [USE CMD or ENTRYPOINT - See below]

For more information on CMD vs ENTRYPOINT:

Principles

Every command is a layer. To minimize the build time:

  • Put your most frequently updated commands toward the end of the docker file.

As an example, copying your code (which presumably you edit more frequently) should probably be one of your last steps..

  • If possible, combine commands into one line to form a single layer.

Building a Docker Image

docker build -t <docker-image-name> .

Running a Docker Image

Syntax Suggestions:


docker run -p <host-port>:<container-port> \
  -e <set environmental variables> \
  <image-name>

Helpful notes:

docker run -p 9000:8080 \
    -e AWS_ACCESS_KEY_ID=$aws_access_key \
     -e AWS_SECRET_ACCESS_KEY=$aws_secret_access_key \
     -e OUTPUT_BUCKET_NAME=$aws_bucket \
     -e NSAND_ACCESS=$nsand_access_key \
     -e NSAND_SECRET=$nsand_secret \
     -e SAND_ACCESS=$sand_access_key \
     -e SAND_SECRET=$sand_secret \
     -e AWS_LAMBDA_FUNCTION_TIMEOUT=1800 \
     -e AWS_REGION=$aws_region nodd-metrics-cleaner

Note: Using the Docker Run command with the -it flag is a good way to step into the running container to a bash shell to both develop and see what is going on.

More info on Docker Run: Docker Run Docs

Finding running Docker Containers

Docker can run multiple containers at once (it can even run multiple containers from the same image, which is quite useful).

To find out which Docker containers are running, use docker ps. You’ll notice Docker borrows heavily from Linux and Git when it comes to naming its commands.

docker ps
CONTAINER ID   IMAGE                           COMMAND                  CREATED              STATUS              PORTS                NAMES
51aa22390e18   pangeo/pangeo-notebook:latest   "/srv/start jupyter …"   About a minute ago   Up About a minute   0.0.0.0:8080->8888   busy_blackwell
  • CONTAINER ID: hexadecimal string of 64 characters that uniquely identifies the container.
  • IMAGE: the name of the image running in the container.
  • COMMAND: any commands passed to docker run along with the image.
  • CREATED: how long ago the container was created.
  • STATUS: whether the container is running, exited, paused, restarting, etc.
  • PORTS: what external ports the container might be bound to.
  • NAMES: similar to CONTAINER ID, but much easier to type. These are randomly assigned by Docker.

Accessing and exploring running containers

Sometimes it’s useful to access a running container in order to diagnose bugs and test potential solutions. You can access a container via:

docker exec -it <CONTAINER NAME> bash
  • docker exec: execute a command in a running container
  • -i: interactive
  • -t: allocate a pseudo-TTY (ie, pull up a terminal console from within the running container)
  • <CONTAINER NAME>: whatever NAME Docker randomly assigned to this container.
  • bash: the shell that we want to use to interact with the container.

Run this command and then explore around the container. You can interact with it like you would any Linux operating system.

Removing running containers

And sometimes it’s useful to kill running containers. This need usually arises when you’re experimenting with formulating the correct Dockerfile for a specific project.

First run docker ps to get a list of all running containers. To kill a specific container, run:

docker kill <CONTAINER NAME>

Run docker ps again afterwards. That container ought to have disappeared from the list.

Additional References