Panamax application templates allow you to deploy your applications with one click, to whatever cloud target you want. Keep reading to learn how to create your own application templates and simplify your deployment workflow with Panamax's intuitive UI.

While your first experience with Docker was probably tinkering with it via the CLI, you may have quickly become tired of manually configuring and managing each container independently. Wouldn't it be great if you could just customize everything in one place, and tell Docker to fire up all of your containers with one command?

Application templating allows you to do just that. There are a few different choices for authoring templates, including Docker Compose (formerly Fig) and Panamax, but the basic principle is universal across all tools: provide everything necessary to get your application running -- services, variables, dependencies, you name it -- and build it with one command.

Specifically, Panamax templates are powerful because Panamax allows you to deploy your applications with one click, either on your local machine or on a variety of remote hosts like AWS, Google Cloud or CenturyLink Cloud. This is a useful workflow if you'd like to test your code in multiple environments, easily package your code, share a prototype you've been working on, or allow other Panamax users to build your application.

There are two basic strategies for working with application templates in Panamax. The first is to author the template from scratch and save it out as a template.pmx file. The .pmx files are very similar to .yml, which was done on purpose. For this reason, it's easy to go back and forth between Docker Compose and Panamax. Here is a sample Panamax template:

name: GitLab Single node
images:
- category: GitLab
     name: sameersbn_gitlab_latest
     source: sameersbn/gitlab:7.1.1
     description:
     type: Default
     expose:
     - '22'
     - '80'
     - '443'
     ports:
     - host_port: '10022'
   container_port: '22'
     - host_port: '10080'
   container_port: '80'
     - host_port: '443'
   container_port: '443'
     links: []
     environment:
     - variable: GITLAB_PORT
   value: '10080'
     - variable: GITLAB_SSH_PORT
   value: '10022'
     volumes: []

The second way to work with templates is by building your application with Panamax and saving it as a template -- no typing or formatting required. Below, I'll explain some Panamax features and best practices to aid you as you templatize your application.

Customizing your application

After installing and firing up Panamax, you can start building your application by searching for images to include. Panamax search will query the Docker Registry as well as any private registries you've set up. You can even specify an absolute path to an image. While working directly with images -- not existing templates -- your only option is to deploy the image locally.

For any image, you can use Panamax to customize the container to include volume mount points, environment variables, and port mappings.

nginx

A feature specific to Panamax is the concept of service categories. By grouping your services into logical categories, it's easier for other users of your template to see your application's architecture. You can create categories, rename those categories, assign services to categories, and even reorder services within categories all on the application details page. Within your application, you can move a service from one category to another by dragging and dropping it. Additionally, you have the capability to create a new category by clicking the button in the "Add Category" panel.

nginx-categories

Note that these categories exist in the presentation layer, but have no impact on the way your application performs. However, they are a useful way to outline service architecture to future users of your template.

Saving your application as a template

After you've configured your application, saving it as a template is easy. From either your application list page, or the application details page itself, click "Save as Template." If it is your first template, you'll be asked for a GitHub access token so that Panamax can save your template to a repository. You can create a new authorization token directly on GitHub.

application

When saving your template, you have the opportunity to provide additional details about the application and its intended use. The template's icon will accompany its name in search results, and keywords will help other Panamax users find your template. Most importantly, it's essential that you include documentation. Even a simple application requires quite a few customizations to get it up and running.

In order for other developers to easily use your template, make sure to document any necessary configurations needed to run it. This includes environment variables, port bindings, and virtual machine requirements (like memory and CPU). Check out the suggestions for creating good template documentation.

Searching for and Deploying Templates

Templates within your source repositories will come back in search results for any matching term. You will be able to see a short description of the template as well as how many services (containers) it includes. Clicking Run Template will give you two options: either running locally (great for testing!) or deploying remotely. For an introduction to remote deployments, check out the documentation or read the blog post. And that's it! Your application is now running without having to fire up containers individually.

Source Repositories

Panamax also provides you with the capability to access templates from any public GitHub repository. You can find a list of your template source repositories on the Dashboard. When you drill down into your sources, you can see how many templates are in each repo and when it was last refreshed. You also have the option to refresh the source in order to load any new templates you may have created. To add a repository, just click "Add a New Source" and provide the username and repository name. The templates will be loaded, and you'll be able to see those templates in the search results.

Template Best Practices

Use official, versioned images, or images with a Dockerfile

Make sure the images included in your application have a Dockerfile, which is valuable when trying to troubleshoot. It's a good idea to have a record of exactly how your images are being constructed. If using a remote image, you can check out the image by viewing it on the Docker Registry.

Almost all images have a tag 'latest' that is run by default. This is a running tag which encapsulates whatever the most recent code on master is. This can be problematic because code changes rapidly -- the newest version of the image could work slightly differently than the version you ran, creating a problem in your template. If possible, try to use a version tag to avoid potential conflicts.

Documentation

Again, be sure to include as much documentation as possible with your template. If you're not sure what to include, check out the suggestions for creating good template documentation.

Consider Template Portability

Selecting a specific host port for your port mappings and bind mounting directories from your host OS can be useful tools but might limit the re-usability and portability of your template. If you can simply provide instructions on mappings or bound directories, it may make your template more usable for others.

Future users of your template may have a use case that is very different from yours, so if it makes sense within the context of your application, avoid hard and fast definitions when you could instead provide instructions.