So you’re interested in learning more about Porter? Great! This guide will walk you through key concepts of managing bundles. You will use the porter CLI to install, upgrade, and uninstall the bundle.


Docker is a prerequisite for using Porter. Docker is used to package up the bundle.

If you do not have Docker installed, go ahead and get Docker.

Getting Porter

Next, you need Porter. Follow the Porter installation instructions.

Porter Key Concepts

For this quickstart, the main concepts that you will use include:

  • Bundle - A bundle is your application artifact, client tools, configuration and deployment logic packaged together.
  • Installation - An instance of a bundle installed to your system.
  • Tag - A reference to the bundle in an OCI registry that contains the registry, bundle name, and version, e.g. myregistry.com/mybundle:v1.0.
  • Registry - An OCI compliant artifact store. Many Docker registries are now OCI compliant and work with bundles, here’s a list of popular registries have been tested with Porter.

Understand a Bundle

Before using a bundle that you’ve found, you can view information about the bundle with porter explain. Use this command to see:

  • a description of the bundle
  • parameters and credentials used by the bundle
  • custom actions that you can run, for example viewing status or logs
  • outputs generated by the bundle
  • dependencies of the bundle
$ porter explain getporter/wordpress:v0.1.3
Name: wordpress
Version: 0.1.3

Name         Description   Required   Applies To
kubeconfig                 true       All Actions

Name                 Description   Type     Default               Required   Applies To
namespace                          string                         false      All Actions
wordpress-name                     string   porter-ci-wordpress   false      All Actions
wordpress-password                 string   <nil>                 true       install,upgrade

Name   Description   Modifies Installation   Stateless
ping   ping          true                    false

Alias   Reference
mysql   getporter/mysql:v0.1.3

For this quickstart we are going to use the hello world bundle which is a bit simpler:

$ porter explain ghcr.io/getporter/examples/porter-hello:v0.2.0
Description: An example Porter configuration
Version: 0.2.0

Install a Bundle

To install a bundle, you use the porter install command.

porter install porter-hello --reference ghcr.io/getporter/examples/porter-hello:v0.2.0

In this example, you are installing the v0.2.0 version of the ghcr.io/getporter/examples/porter-hello bundle from its location in the default registry (Docker Hub) and setting the installation name to porter-hello.

List Bundle Installations

To see the list of bundle installations, use the porter list command.

$ porter list
porter-hello      21 minutes ago   21 minutes ago   install       succeeded

In this example, it shows the bundle metadata along with the creation time, modification time, the last action that was performed, and the status of the last action.

Show Installation Information

To see information about an installation, use the porter show command with the name of the installation.

$ porter show porter-hello
Name: hello
Bundle: ghcr.io/getporter/examples/porter-hello
Version: 0.2.0
Created: 2021-05-24
Modified: 2021-05-24

  Run ID                      Action   Timestamp   Status     Has Logs
  01F1SVDSQDVKGC0VAABZE9ERQK  install  2021-03-27  failed     true
  01F1SVVRGSWG3FKY2ZATN4XTKC  install  2021-03-27  succeeded  true

Upgrade the Installation

To upgrade the resources managed by the bundle, use porter upgrade.

Upgrade using a version tag

Most bundles are written such that a specific version of the bundle corresponds to a specific version of an application. So to upgrade the application to a new version you need to specify a newer version of the bundle.

$ porter upgrade porter-hello --version 0.2.0
upgrading porter-hello...
executing upgrade action from porter-hello (installation: porter-hello)
Upgrade Hello World
Upgraded to World 2.0
execution completed successfully!

Upgrade using digest

When working in production environment, we highly recommend you to reference the bundle using its digest instead of tag. We used tags in our docs for simplicity, but tags can be overwritten which results in unexpected outcomes from upgrading an bundle. For deterministic and repeatable deployments, use digests instead of tags to ensure that you deploy exactly what you intended.

$ porter upgrade porter-hello --reference ghcr.io/getporter/examples/porter-hello@sha256:276b44be3f478b4c8d1f99c1925386d45a878a853f22436ece5589f32e9df384
upgrading porter-hello...
executing upgrade action from porter-hello (installation: porter-hello)
Upgrade Hello World
Upgraded to World 2.0
execution completed successfully!


If you received an invalid media type error like below, check that you are referencing the digest for the bundle and not the installer image.

unable to pull bundle: invalid media type "application/vnd.docker.distribution.manifest.v2+json" for bundle manifest


To clean up the resources installed from the bundle, use the porter uninstall command.

porter uninstall porter-hello

Next Steps

In this QuickStart, you learned how to use some of the features of the porter CLI to explain a bundle, install and manage its lifecycle.