Getting Started with Panamax on Mac OS X

There are a lot of posts out there about Docker and Panamax and there is nothing in this one that is unique. I'm recording my thoughts here for my own future reference, but it may be helpful for others that are kicking the tires. Check out the announcement post on the CenturyLink Labs site for more background on Panamax.

Panamax simplifies the process of building multi-container applications in a microservices architecture. While Docker already supports linking multiple containers it is a non-trivial undertaking and there are still challenges associated with keeping the containers running across a cluster of hosts. Panamax combines containers with CoreOS and fleet to provide distributed cluster management as well as scheduling and orchestration. If you build an application with 4 containers fleet will ensure that the containers stay running. The future direction clearly includes multi-host clustered deployments of apps but today Panamax is restricted to a single machine.

Optional - Install Homebrew

I assume you are using Homebrew on your Mac. If you haven't already installed it follow these steps:

Run the following command in Terminal to begin the Homebrew installation:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

The script will explain what the installation process will do and prompt you to confirm proceeding:

==> This script will install:
/usr/local/bin/brew
/usr/local/Library/...
/usr/local/share/man/man1/brew.1
==> The following directories will be made group writable:
/usr/local/.
/usr/local/bin
==> The following directories will have their group set to admin:
/usr/local/.
/usr/local/bin
Press RETURN to continue or any other key to abort  

You will be prompted to enter your password so the installer can run as root and complete the installation:

==> /usr/bin/sudo /bin/chmod g+rwx /usr/local/. /usr/local/bin
Password: ***********  
==> /usr/bin/sudo /usr/bin/chgrp admin /usr/local/. /usr/local/bin
==> /usr/bin/sudo /bin/mkdir /Library/Caches/Homebrew
==> /usr/bin/sudo /bin/chmod g+rwx /Library/Caches/Homebrew
==> Downloading and installing Homebrew...
remote: Counting objects: 196644, done.  
remote: Compressing objects: 100% (53260/53260), done.  
remote: Total 196644 (delta 142208), reused 196644 (delta 142208)  
Receiving objects: 100% (196644/196644), 40.52 MiB | 166.00 KiB/s, done.  
Resolving deltas: 100% (142208/142208), done.  
From https://github.com/Homebrew/homebrew  
 * [new branch]      master     -> origin/master
HEAD is now at c5ea5df multimarkdown 4.5.3  
==> Installation successful!
==> Next steps
Run `brew doctor` before you install anything  
Run `brew help` to get started  

Run brew doctor before you do anything else.

Install Panamax

Before you begin VirtualBox 4.2 or higher and Vagrant 1.6 or higher will need to be installed. Refer to the Installing VirtualBox and Vagrant on Mac OS X Mavericks post if you are missing either.

To download the Panamax package using Homebrew run the following command:

$ brew install http://download.panamax.io/installer/brew/panamax.rb
######################################################################## 100.0%
==> Downloading http://download.panamax.io/installer/pmx-installer-0.2.0.zip
######################################################################## 100.0%
Warning: If upgrading the Panamax Installer, be sure to run 'panamax reinstall' to ensure compatibility with other Panamax components.  
  /usr/local/Cellar/panamax/0.2.0: 5 files, 28K, built in 2 seconds

Install and run Panamax:

panamax init  

The installer will then:

Download the panamax-coreos-box-410 VirtualBox image from http://storage.core-os.net/coreos/amd64-usr/410.0.0/coreosproductionvagrant.box.

Forwards the VM ports to localhost (your Mac) as follows:

panamax-vm: 3000 => 8888  
panamax-vm: 3001 => 8889  
panamax-vm: 22 => 2222  

Rsync between ~/.panamax/ on your Mac and /var/panamax in the VM.

Initiates docker pulls for the three images that make up Panamax: panamax-api, panamax-ui, and cAdvisor.

==> panamax-vm: docker pull centurylink/panamax-api:latest
==> panamax-vm: docker pull centurylink/panamax-ui:latest
==> panamax-vm: docker pull google/cadvisor:0.2.2

After all three containers are running the Panamax web interface will launch at http://localhost:8888/.

Install Rails with PostgreSQL Template

Enter "rails" into the Search field on the Panamax web interface and click "Run Template" for "Rails with PostgreSQL":

Panamax will pull down two docker containers: dharmamike/pmx-pgsql and dharmamike/pmx-rails. It also runs bundler to install all the necessary RubyGems.

After the deployment process completes you’ll have two “Application Services” and the HTTP server built in to Rails, WEBrick, will be running on port 3000.

At this point a vanilla Rails app is running on port 3000 within the container and Panamax has a port binding configured to map container port 3000 to the CoreOS host on port 8080. You can see the port binding by clicking the “Rails” entry under “Web Tier.”

You can’t access the Rails app from your Mac OS X client until you create a port forwarding rule in VirtualBox. It can be done using the VirtualBox GUI, but the easiest way is to run the following command which creates a rule named “lmx-rails-pgsql” that maps the CoreOS VM port 8080 to Mac OS X localhost port 9080:

$ VBoxManage controlvm panamax-vm natpf1 pmx-rails-pgsql,tcp,,9080,,8080

You can now access the Rails app at http://localhost:9080 from your Mac OS X client.

Summary

This post walks through setting up a CoreOS VM with the three Panamax Docker containers on a Mac OS X client and deploying a simple Ruby on Rails template. Once Panamax supports multiple hosts I’ll revisit the deployment process. In discussions with a member of the Panamax development team Mesos integration is a future goal as well. As native Docker support in Mesos and Marathon improves it should be possible to wire up a multi-container application using Panamax that can be deployed on a Mesos cluster.

For an example of decomposing a legacy application into multiple Docker containers check out this post on the CenturyLink Labs site.