Portainer icon

Portainer

Interact with Portainer via API

Actions190

Stacks → Stack Create Docker Swarm File

AI-generated

Overview

This node operation allows you to create a new stack in a Docker Swarm environment managed by Portainer using a stack file. It is useful for automating the deployment of containerized applications defined by Docker Compose files or similar stack definitions directly into a Swarm cluster. Typical use cases include continuous deployment pipelines, infrastructure automation, and managing multi-container Docker applications programmatically.

For example, you can use this node to deploy a microservices application described in a Docker Compose file to a specific Docker Swarm cluster by providing the stack file content, environment variables, and target swarm cluster ID.

Properties

Name Meaning
Endpoint Id Identifier of the environment (Docker endpoint) where the stack will be deployed.
Name The name assigned to the stack being created.
Swarm ID Identifier of the Docker Swarm cluster where the stack will be deployed.
Env Optional environment variables passed during deployment, formatted as a JSON array of objects with name and value keys. Example: [{"name": "VAR1", "value": "value1"}].
File The stack file content defining the services and configuration of the stack (typically a Docker Compose YAML file).

Output

The node outputs JSON data representing the response from the Portainer API after attempting to create the stack. This typically includes details about the newly created stack such as its ID, name, status, and any relevant metadata returned by the API.

No binary data output is expected from this operation.

Dependencies

  • Requires an active connection to a Portainer instance via an API key credential.
  • The Portainer URL and authentication credentials must be configured in n8n.
  • The target Docker environment (endpoint) and Swarm cluster must be accessible by Portainer.

Troubleshooting

  • Common issues:

    • Invalid or missing endpoint ID or swarm cluster ID may cause deployment failures.
    • Malformed stack file content (invalid YAML or unsupported features) can result in errors.
    • Incorrect environment variable formatting (not a valid JSON array) may cause the deployment to fail.
    • Network connectivity issues between Portainer and the Docker Swarm cluster can prevent stack creation.

  • Error messages:

    • Authentication errors indicate invalid or missing API credentials.
    • Validation errors from the API often point to incorrect property values or missing required fields.
    • Timeout or connection refused errors suggest network or service availability problems.

To resolve these, verify all input parameters, ensure the stack file is correctly formatted, confirm that the Portainer API credentials are valid, and check network connectivity.

Links and References

Discussion