Docker on macOS: Getting Started

Running a Web App in a Docker Container

Many iOS apps communicate with a web server, which is also the back end of a web app. And you often want interactions with the iOS app to be reflected in the web app, and vice versa. You can run the web app locally without containers, but running it in containers can make it easier to test different configurations in isolation, or to test user types with different privileges.

To run a web app in a container, the first thing you need to learn is how to access the container’s ports in your browser’s localhost. The Docker term is publishing ports. In this section, you’ll learn about publishing ports, and also take a quick look at the default Docker image registry Docker Hub.

Publishing Ports

Actually, you don’t need artificial intelligence to figure out ports! The syntax is --publish followed by two port numbers, separated by a colon. The trick is remembering the first value is for the host here, and the second value is for the container there — you’re publishing a port here from there. For the first number — the host’s port — you can specify any number you like, but the easiest option is to use the same number as the container’s port. For the second number, you’re stuck with whatever the container exposes — you’ll get an error if you try to change it. The ability to publish the container’s port to different localhost ports makes it easy to run several web app containers at the same time.

Start with a really simple web app from IBM Kitura. In a browser, load the default registry for Docker images at Docker Hub. Enter kitura in the Search field, then select the first returned item:

Open a new terminal window — this will be your Docker run terminal window. Sometimes, you’ll run a process in the foreground in this window, so you won’t be able to run any housekeeping commands in it. That’s where your Docker cleanup window will come in handy!

Click the copy icon for the Docker Pull Command, and paste it in your Docker run terminal window:

docker pull ibmcom/kitura-ubuntu

The ibmcom/kitura-ubuntu image layers a simple web app onto the Kitura application framework, which is layered onto the swift-ubuntu image, which is the Swift programming language layered on top of the Ubuntu operating system. Ubuntu is a version of Linux.

The image’s Docker Hub page doesn’t give any specific running instructions, so just go ahead and try it:

docker run ibmcom/kitura-ubuntu

The container starts, with these messages:

[2018-10-02T21:53:57.690Z] [WARNING] [ConfigurationManager.swift:261 load(url:
  deserializerName:)] Unable to load data from URL 
  /Kitura-Starter/config/mappings.json
[2018-10-02T21:53:57.698Z] [INFO] [main.swift:28 Kitura_Starter] Server will be 
  started on 'http://localhost:8080'.
[2018-10-02T21:53:57.703Z] [INFO] [HTTPServer.swift:124 listen(on:)] Listening 
  on port 8080

It tried but failed to load data from a JSON file, then started listening on localhost:8080. Notice you didn’t get the Unix shell prompt back — this process is running in the foreground, and hasn’t exited.

Open a browser at localhost:8080 — nope, “Can’t Connect to the Server”. What’s happening? The container exposes port 8080 in its own environment, but you must publish this port to a port on the host system, to see what’s there.

First, get rid of this try-out container: In your Docker cleanup window, run a command to find the container’s ID, stop the container, then remove it. Because there’s only one container running, you can use a command, with two levels of $() nesting, that stops and removes all running containers. Try to work this out on your own before you check the solution below.

[spoiler title=”Solution”]docker rm $(docker stop $(docker ps -q))

This command stops and removes all running containers. If you have running containers you want to keep running, use docker ps on its own to find the ID of the running container you want to stop and remove.[/spoiler]

Go back to your Docker run terminal window — the Unix shell prompt has returned. Enter this command:

docker run -p 80:8080 --name kitura -d ibmcom/kitura-ubuntu

The -p option, short for --publish, maps the really local localhost:80 to the container’s 8080 port. The --name option specifies the container name. The -d option, short for --detach, runs the container process in the background, so you get the Unix shell prompt back right away.

In a browser, open localhost:80 to see this welcome page:

Run a second container on a different port:

docker run -p 90:8080 --rm --name kitura2 ibmcom/kitura-ubuntu

In the browser, open localhost:90 to see the same welcome page.

This time, the container is running in the foreground — you didn’t use the -d option, so you didn’t get the Unix shell prompt back. Also, the --rm option means the container will be removed when you stop it.

In your Docker cleanup window, enter this command:

docker stop kitura2

It might take several seconds before it echoes kitura2, and the Unix shell prompt returns in your Docker run window.

Use docker ps -a to see that there are no Exited containers:

CONTAINER ID  IMAGE                .. STATUS       PORTS                  NAMES
f64f7eb69258  ibmcom/kitura-ubuntu .. Up 47 sec..  0.0.0.0:80->8080/tcp   kitura

The first container is still running in the background, so enter this command to stop it:

docker stop kitura 

When the Unix shell prompt returns, refresh the localhost:80 page — it won’t load, because you stopped the container process.

Use docker ps -a to check the first container still exists, then run this command to restart it:

docker start kitura 

Refresh the localhost:80 page — this time it works!