Add a new stack

Options when deploying a new stack

There are four ways to deploy a new stack from Portainer:

Option 1: Web editor

From the menu select Stacks, click Add stack, give the stack a descriptive name then select Web editor. Use the web editor to define the services.

You can search within the web editor at any time by pressing Ctrl-F (or Cmd-F on Mac).

As part of the stack creation you can enable a stack webhook, allowing you to remotely trigger redeployments of the stack from your repository, for example. You can read more on this in our documentation on stack webhooks.

As an optional step, you can also use the web editor to define environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc).

Environment variables can be set individually within Portainer or you can use Load variables from .env file to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an environment definition:

environment:
  MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE}

Alternatively, on Docker Standalone environments you can add stack.env as an env_file definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file:

env_file:
  - stack.env

Note: Using env_file to define a file does not work in Docker Swarm due to the lack of env_file support in docker stack deploy (used on Swarm environments to deploy your stack). On Docker Swarm, you will need to define each environment variable manually.

Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself. You will still see the ${MY_ENVIRONMENT_VARIABLE} style entry in the compose file.

When you're ready, click Deploy the stack.

Option 2: Upload

In Portainer you can create stacks from Compose YML files. To do this, from the menu select Stacks, click Add stack, then give the stack a descriptive name.

Select Upload then select the Compose file from your computer.

As part of the stack creation you can enable a stack webhook, allowing you to remotely trigger redeployments of the stack from your repository, for example. You can read more on this in our documentation on stack webhooks.

As an optional step, enter any environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc).

Environment variables can be set individually within Portainer or you can use Load variables from .env file to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an environment definition:

environment:
  MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE}

Alternatively, you can add stack.env as an env_file definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file:

env_file:
  - stack.env

Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself which would take it out of sync with your local copy. You will still see the ${MY_ENVIRONMENT_VARIABLE} style entry in the compose file.

When you're ready click Deploy the stack.

Option 3: Git repository

If your Compose file is hosted in a Git repository, you can deploy from there. From the menu select Stacks, click Add stack, then give the stack a descriptive name.

Select Git Repository then enter information about your Git repo.

Any Git-compatible repository should work here. Substitute the details as required.

If you have 2FA configured in GitHub, your passcode is your password.

Automatic updates

Portainer supports automatically updating your stacks deployed from Git repositories. To enable this, toggle on Automatic updates and configure your settings.

For more detail on how automatic updates function under the hood, have a look at this knowledge base article.

Relative path volumes

When you toggle Enable relative path volumes to on, you are able to specify relative path references in your compose files. Portainer will create the required directory structure and populate the directories with the relevant files from your Git repository.

This feature is only available in Portainer Business Edition.

This functionality is currently not available on Edge Agent environments.

On Docker Standalone environments, specify the path at which you want your files to be created on your host filesystem in the Local filesystem path field.

Ensure this directory exists on your local filesystem and is writable.

On Docker Swarm environments, specify the path at which you want your files to be created in the Network filesystem path field.

Ensure that this path is available on all of your Docker Swarm nodes and is writable.

Environment variables

As an optional step, you can also set environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc).

Environment variables can be set individually within Portainer or you can use Load variables from .env file to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an environment definition:

environment:
  MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE}

Alternatively, you can add stack.env as an env_file definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file:

env_file:
  - stack.env

Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself which would take it out of sync with the Git repository. You will still see the ${MY_ENVIRONMENT_VARIABLE} style entry in the compose file.

Enter environment variables if required then click Deploy the stack.

Last updated