You can use other CI tools, such as CircleCI, Travis CI, or Gitlab, to deploy your application. These CI tools support running any Docker image as part of a CI workflow. Porter maintains public.ecr.aws/o1j4x7p4/porter-cli:latest, a public Docker image that contains the Porter CLI. This allows you to run Porter CLI commands easily as part of any workflow.

The Porter CLI requires that the following environment variables are set in order to target a specific application:

PORTER_TOKEN
PORTER_PROJECT
PORTER_CLUSTER

These environment variables can be set by logging into the Porter CLI and running porter config.

For an introduction on deploying applications from the CLI, see this section.

Deploying and Updating your Application

In order to update your application on each push to a repository, you can either deploy from a Github repository or a Docker registry. If you deploy from a Github repository, you can delete the created Github actions file and create your own file. If you deploy from a Docker registry, you must have an image to deploy from first — the easiest approach is just to push a “dummy” image to your registry, which will be overwritten when calling porter update from the CI run.

To simply build and re-deploy the application running on Porter, you can call the following:

porter update --app <APP_NAME> --tag <commit-sha>

It is also possible to use a custom command to build your image (such as docker build), and then call porter update push and porter update config to push the image and redeploy your application. See the Advanced Options for more details.

Examples

CircleCI

It is easiest to create a CircleCI Context for each Porter cluster in order to set environment variables for a CircleCI job. In CircleCI, set the following environment variables in a context:

PORTER_TOKEN
PORTER_PROJECT
PORTER_CLUSTER

These environment variables can be found after running porter config from the Porter CLI. Next, you can create the following CircleCI config file to a desired branch of your repository:

version: 2.1

jobs:
  porter:
    docker:
      - image: public.ecr.aws/o1j4x7p4/porter-cli:latest
    steps:
      - checkout
      - setup_remote_docker:
          version: 19.03.13
      - run:
          name: "Update Porter application"
          command: "porter update --app <APP_NAME> --tag $CIRCLE_SHA1 --stream"

workflows:
  version: 2
  porter-staging-workflow:
    jobs:
      - porter:
          context: <CONTEXT_NAME>

Make sure to replace <CONTEXT_NAME> and <APP_NAME> with your actual CircleCI context name and application name.

Advanced Options

This section provides an overview of how you might use certain subcommands to fully customize your deployment pipeline. By default, the command porter update performs four steps: gets the environment variables for the application, builds a new Docker container from the source files, pushes a new Docker image to the remote registry, and calls a Porter endpoint to re-deploy the application. However, we designed this command to be modular: if you would like to add intermediate steps in your own build process, you can call different porter update sub-commands separately:

porter update get-env

Gets environment variables for a deployment for a specified application given by the --app flag. By default, env variables are printed via stdout for use in downstream commands:

porter update get-env --app example-app | xargs

Output can also be written to a dotenv file via the --file flag, which should specify the destination path for a .env file. For example:

porter update get-env --app example-app --file .env

porter update build

Builds a new version of the application specified by the --app flag. Depending on the configured settings, this command may work automatically or will require a specified --method flag.

If you have configured the Dockerfile path and/or a build context for this application, this command will by default use those settings, so you just need to specify the --app flag:

porter update build --app example-app

If you have not linked the build-time requirements for this application, the command will use a local build. By default, the cloud-native buildpacks builder will automatically be run from the current directory. If you would like to change the build method, you can do so by using the --method flag, for example:

porter update build --app example-app --method docker

When using --method docker, you can specify the path to the Dockerfile using the --dockerfile flag. This will also override the Dockerfile path that you may have linked for the application:

porter update build --app example-app --method docker --dockerfile ./prod.Dockerfile

Build caching can be enabled with the --use-cache flag. Note that --use-cache is not supported with the Heroku 18 builder and will automatically push to the image repository linked to the application.

porter update push

Pushes a new image for an application specified by the —app flag. This command uses the image repository saved in the application config by default. For example, if an application “nginx” was created from the image repo “gcr.io/snowflake-123456/nginx”, the following command would push the image “gcr.io/snowflake-123456/nginx:new-tag”:

porter update push --app nginx --tag new-tag

This command will not use your pre-saved authentication set up via docker login, so if you are using an image registry that was created outside of Porter, make sure that you have linked it via porter connect.

porter update config

Updates the configuration for an application specified by the —app flag, using the configuration given by the —values flag. This will trigger a new deployment for the application with new configuration set. Note that this will merge your existing configuration with configuration specified in the —values file. For example:

porter update config --app example-app --values my-values.yaml

You can update the configuration with only a new tag with the —tag flag, which will only update the image that the application uses if no —values file is specified:

porter update config --app example-app --tag custom-tag