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:
These environment variables can be set by logging into the Porter CLI and running
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.
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:
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:
- image: public.ecr.aws/o1j4x7p4/porter-cli:latest
name: "Update Porter application"
command: "porter update --app <APP_NAME> --tag $CIRCLE_SHA1 --stream"
Make sure to replace
<APP_NAME> with your actual CircleCI context name and application name.
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- prints the build environment variables to the terminal or a file.
porter update build- builds the Docker container used for deployment.
porter update push- pushes the Docker container used for deployment to a remote registry.
porter update config- calls a Porter endpoint to re-deploy the application with new configuration.
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
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
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
--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 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