> For the complete documentation index, see [llms.txt](https://docs.portainer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.portainer.io/sts/user/docker/stacks/add.md). # Add a new stack From the menu select **Stacks**, then click **Add stack**. Give the stack a descriptive name, then choose a build method: * **Web editor** - type your compose content directly * **Upload** - upload a `stack.yml` file * **Git repository** - [deploy from a hosted Git repository](#deploying-from-a-git-repository) * **Custom template** - use a pre-defined [template](/sts/user/docker/templates/custom.md)
Once the stack content is defined, you can configure [webhooks](#webhooks), [environment variables](#environment-variables), [registries](#registries), and [access control](#access-control) before deploying. ### Webhooks You can enable a webhook to allow remote triggering of stack redeployments. See [stack webhooks](/sts/user/docker/stacks/webhooks.md) for details.
### Environment variables Environment variables let you define values that vary between deployments, such as hostnames or database names. You can set them individually using **Add an environment variable**, or upload a `.env` file using **Load variables from .env file**. To switch to a view that allows you to paste multiple `key=value` variables, select **advanced mode.** However your variables have been defined, they will be available to use in your compose file using an `environment` definition: ``` environment: MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE} ``` On Docker Standalone and Podman 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 ``` {% hint style="warning" %} **Note:** `env_file` is not supported on Docker Swarm. Define each variable individually instead. {% endhint %} {% hint style="info" %} The compose file itself is not modified when environment variables are set - variables can be updated in Portainer without editing the compose file. You will still see the `${MY_ENVIRONMENT_VARIABLE}` style entry in the compose file. {% endhint %}
### Registries Select the registries to use when deploying the stack. This is useful when your stack pulls images from multiple registries requiring authentication. {% hint style="warning" %} By default, all configured registries are used. If you have multiple registries from the same provider (such as multiple `ghcr.io` registries), explicitly selecting the correct registry ensures the right credentials are used. {% endhint %}
### Access control To restrict management of this stack, enable access control and select one of: * **Administrators only** * **Restricted** - specify the users and teams who should have access
When you're ready, click **Deploy the stack**. ## Deploying from a Git repository If your compose file is hosted in a Git repository, you can deploy directly from it. See the details below on setting up your Git repository. | Field/Option | Overview | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Source | Select your Git repository from your list of preconfigured [sources](/sts/user/app-delivery/sources.md). | | Repository reference | Select the reference to use when deploying the stack (for example, the branch). | | Compose path | Enter the path to the Compose file from the root of the repository. | | Additional paths | Click **Add file** to add additional YAML files to be parsed by the build. This is the equivalent of passing multiple `-f` options to `docker compose`, and abides by the same [merging rules](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/#merging-rules). | | GitOps updates | Toggle this on to enable GitOps updates (see below). |
### GitOps updates To keep your stack automatically in sync with your repository, toggle on **GitOps updates** and configure your settings. {% hint style="info" %} See [this article](/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-automatic-updates-for-stacks-applications-work.md) for details on how GitOps updates work {% endhint %} | Field/Option | Overview | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Mechanism |

Select the method to use when checking for updates:
Polling: Periodically poll the Git repository from Portainer to check for updates to the repository.

Webhook: Generate a webhook URL to add to your Git repository to trigger the update on demand (for example via GitHub actions).

| | Fetch interval | If **Polling** is selected, define how often Portainer will check the Git repository for updates. | | Webhook | When **Webhook** is selected, this field displays the webhook URL to use in your integration. Click **Copy link** to copy the webhook URL to the clipboard. |

Automatic updates when using polling

Automatic updates when using webhooks

| Field/Option | Overview | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Re-pull image |

Enable this setting to always pull the most recent version of container images when updating the stack. This is equivalent to the --pull=always flag for docker run.
This option was previously labeled as Pull latest image.

| | Force redeployment |

Enable this setting to force the redeployment of your stack at the specified interval (or when the webhook is triggered), overwriting any changes that have been made in the local environment, even if there has been no update to the stack in Git. This is useful if you want to ensure that your Git repository is the source of truth for your stacks and are happy with the local stack being replaced.

If this option is left disabled, automatic updates will only trigger if Portainer detects a change in the remote Git repository.

|
### Relative path volumes {% hint style="info" %} Enabling relative path volumes is available in Business Edition only. {% endhint %} Toggle on **Enable relative path volumes** to use relative path references in your compose files. Portainer will create the required directory structure and populate it with files from your Git repository. * **Docker Standalone / Podman** - specify the path in the **Local filesystem path** field. The directory must exist on your host filesystem and be writable. * **Docker Swarm** - specify the path in the **Network filesystem path** field. The path must be available and writable across all Swarm nodes. See [this article](/sts/advanced/relative-paths.md) for more detail on how relative path volumes work.