Docker Setup and Basic Use

To help you set up and MySQL server on your computer, we will use “Docker.” Using Docker, we can create a “virtual Linux environment,” a.k.a container, on any computer and install and run any Linux programs inside it. This way, we can run any Linux software on your computer even if its operating system (OS) is Windows or MacOS.

Install Docker App

Go to the Docker Installation Page and download the appropriate installer for your OS.

  1. MacOS: If you are using Mac, we recommend Docker Desktop for Mac.
  2. Windows: If you are using Windows 10, we recommend Docker Desktop for Windows after enabling the WSL 2 (Windows Subsystem for Linux). See this page to learn how to install Docker Desktop and WSL 2.
  3. If your system does not meet the requirements for Docker Desktop for Mac/Windows, install Docker Toolbox.

Once you finish installing the App, reboot your computer to ensure that all Docker drivers and programs are properly set up and running.

Test Installation of Docker Application

After installing Docker App, run the Docker app by clicking its icon. This will start docker daemon in the background, which will wait for docker command from the user. (If you are using Docker Toolbox, you do NOT need to execute a separate Docker app first.)

Let us make sure that our Docker has been successfully installed by executing the following command in a command-line window (such as Terminal on Mac, Command Prompt or Windows Terminal on Windows)

$ docker run -it hello-world

Note: The beginning dollar sign $ in the above line is a “common Unix convention” to indicate that the command should be typed into a command-line window. What you actually type is docker run -it hello-world, excluding the dollar sign at the beginning.

Note: If you are using Docker Toolbox, all docker commands must be executed in Docker QuickStart terminal, not the standard Windows command prompt.

You need to have an Internet connection to execute the above command first time. If the above command gives an output similar to the following, congratulations! You have successfully installed Docker on your machine.

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
ca4f61b1923c: Pull complete
Digest: sha256:445b2fe9afea8b4aa0b2f27fe49dd6ad130dfe7a8fd0832be5de99625dad47cd
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.
...
For more examples and ideas, visit:
 https://docs.docker.com/engine/userguide/

Docker Image and Container

Now that you have successfully installed Docker, it is time to learn about important concepts related to Docker: Docker image and Docker container. Roughly speaking, a Docker image is like an OS installation package (such as a Windows installation ISO or macOS installation package) and a Docker container is like an actual system that is setup using the image (such as your laptop). Just like you can set up multiple machines using one OS installation package, it is possible to create multiple containers using one Docker image.

In fact, when you executed the following command earlier,

$ docker run -it hello-world

Docker performed the following sequence of operations

  1. It first downloaded the Docker image named “hello-world” over the Internet from the Docker Hub and saved it locally. Docker Hub is the default location from which Docker images are downloaded.
  2. It then created a Docker container based on the downloaded image.
  3. Finally, it started running the container, displaying any output from the container on terminal.

After Docker images and containers have been download and created, you can see the list of locally available images and containers through the following commands:

$ docker image ls
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
hello-world         latest              f2a91732366c        5 weeks ago         1.85kB

The docker image ls command shows all Docker images that have been saved locally. In this example, we have the “hello-world” image that was downloaded from our earlier docker run ... command.

$ docker container ls -a
CONTAINER ID  IMAGE        COMMAND   CREATED      STATUS                 PORTS  NAMES
ceb7f467442e  hello-world  "/hello"  an hour ago  Exited (0) an hour ago        loving_volhard

The docker container ls -a command shows all Docker containers that have been created. Note the last “NAMES” column in the output, which has the value “loving_volhard” in this example. (This value is likely to be different on your machine.) Whenever Docker creates a new container, it assigns a unique random name – in our example “loving_volhand” – so that the user can refer to the container using the name in future commands. For example, if we want to start the “loving_volhard” container again, we can execute

$ docker container start -i loving_volhard   # replace loving_volhard with your container name

which will print out the “Hello from Docker!” and some help messages on the terminal.

NOTE: docker container ls -a shows all containers that have been created. If you want to see only the currently-running containers, you can use the docker container ls command without -a (-a means all).

Download and Run MySQL-Apache Container

Now you are ready to download and set up a Docker container for the MySQL server.

Note: If you mess up somehow and want to start from scratch for this part, please run the command docker container rm mysql-apache first before you restart. This will remove the docker container that may have been created while you are following the instructions.

First, create a directory on your computer where you will create and maintain files for this class. In this tutorial, we will assume to use /Users/cho/cs143/ as such a directory. Then execute the following command after replacing {your_shared_dir} with the just created directory name (i.e., /Users/cho/cs143/, note the removal of curly braces { }!):

$ docker run -it -v {your_shared_dir}:/home/cs143/shared -p 8888:80 --name mysql-apache junghoo/mysql-apache

Note:

FYI, the above command asks Docker to perform the following actions:

  1. Image name: From Docker Hub, download and save the image “junghoo/mysql-apache”.
  2. Container name: Create a container from the downloaded image and name it “mysql-apache” (the --name mysql-apache option).
  3. Shared folder: “Connect” the {your_shared_dir} (i.e., /Users/cho/cs143/) directory on your computer with the /home/cs143/shared directory in the Docker container. Once set up, any file you place in the /Users/cho/cs143 directory on your computer will be available in the /home/cs143/shared directory within the Docker container, and vice versa.
  4. Port Forwarding: “Forward” the port 8888 in the host to the port 80 in the container.
  5. Interactive terminal: Allocate a pseudo terminal in the container (-t option) and connect it to the interactive terminal window of the host computer (-i option).

When you execute the above command, you are likely to see a sequence of output similar to the following:

Unable to find image 'junghoo/mysql-apache:latest' locally
latest: Pulling from junghoo/mysql-apache
8911c72a405a: Pull complete
53c82ba785ac: Pull complete
1a3ab8c30468: Pull complete
...
Digest: sha256:14984dbf649cd404610c5e2fc8f860d69a3a9ad77939c45e316cb9fe8ff24c35
Status: Downloaded newer image for junghoo/mysql-apache:latest
 * Starting MariaDB database server mysql
 * Starting Apache httpd web server apache2                                   
 *
cs143@f698df89cf00:~$

Be patient, because the image “junghoo/mysql-apache” is quite large (~ 400MB) and may take a while to download. Eventually, the “mysql-apache” container created from the image “junghoo/mysql-apache” starts MySQL server, and runs a linux shell, giving you the following prompt:

cs143@3fb1a5fafccf:~$

Note that this shell is running in the container (not on your Windows or Mac computer), and any command that you type now will be executed inside the container. For example, if you type pwd (a unix command that prints out the current directory),

cs143@3fb1a5fafccf:~$ pwd
/home/cs143

it prints /home/cs143, the current working directory in the container. Also, if you type whoami (a unix command that prints out the current user name),

cs143@f3339ccac015:~$ whoami
cs143

it prints cs143 which is your username in the container.

Note: Remember that your username is cs143 with the password password in the container.

Shared Folder

Many projects in this quarter should be done within the mysql-apache container that we just set up. To make it easy to share files between your host computer and the mysql-apache container, we just created a shared folder between them through the option -v /Users/cho/cs143:/home/cs143/shared. Any file that you add to the /Users/cho/cs143 directory on your host Windows/Mac computer is accessible at the /home/cs143/shared directory within the container and vice versa. Add a new file to /Users/cho/cs143 on your host and verify that the file is accessible within the container. Delete the file in the container and verify that the file also disappears in /Users/cho/cs143 of the host. If you are not familiar how to access files in a directory within Unix, please go over our Unix Tutorial for Beginners.

Note for Windows Users: Again, if you encounter an issue due to the shared folder setting, please see our Windows FAQ page to troubleshoot.

Running MySQL Client

When you run the mysql-apache container, MySQL server automatically starts. Inside the container, you can run the MySQL client through mysql command:

cs143@3fb1a5fafccf:~$ mysql
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 8
Server version: 10.3.10-MariaDB-1:10.3.10+maria~bionic mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

Within the MySQL client, you can execute any MySQL command. For example, you can print all existing databases by executing show databases:

MariaDB [(none)]> show databases;
+--------------------+
| Database           |
+--------------------+
| class_db           |
| information_schema |
+--------------------+
2 rows in set (0.001 sec)

MariaDB [(none)]>

To exit from the MySQL client, type exit:

MariaDB [(none)]> exit
Bye
cs143@3fb1a5fafccf:~$

Accessing Apache Server

The mysql container has Apache server and PHP preinstalled. starts the Apache server when it boots up. While the Apache server listens on port 80 for HTTP requests, since the host’s port 8888 is forwarded to the container’s port 80, the Apache server can be accessed at the URL http://localhost:8888. Open a browser from you host machine and access the URL http://localhost:8888. If everything is running properly, you will see a page similar to the following:

Note: In case you are using Docker Toolbox and your browser does not display a page at http://localhost:8888, run docker-machine ls in your docker quick-start terminal to determine where your container is running. It may be 192.168.99.100, for example. Then, visit http://192.168.99.100:8888 instead of http://localhost:8888 using your browser.

Shutting Down and Restarting Container

Once you are done with interacting with the container, type exit in the shell:

cs143@f3339ccac015:~$ exit
exit
Initiating the shutdown process...
 * Stopping Apache httpd web server apache2
 *
Container has been shutdown...

When the shell exits, the container will shut itself down, and send you back to your host machine.

From now on, if you need to start the “mysql-apache” container again, use the docker start command inside Terminal App (Mac), Command windows (Windows), or Docker QuickStart Terminal (Docker Toolbox):

$ docker start -i mysql-apache
 * Starting MariaDB database server mysqld                             [ OK ]
 * Starting Apache httpd web server apache2
 *
cs143@f3339ccac015:~$

If you need to stop a running container from your host computer (not by typing exit within the container shell), you can use docker stop command:

$ docker stop mysql-apache

Docker-Command Cheat Sheet

Here we provide a list of frequently-used docker commands. The first three commands have been used and explained in this tutorial.