Managing Multi‑Container Deployments with Portainer Stacks

The Problem: Fragmented Container Management

\n

Managing a multi‑container application via the command line requires manual execution of docker-compose up across various hosts, making it difficult to track versioning and environment variables across a team. When containers are deployed individually, the logical relationship between a database, a backend API, and a frontend proxy is lost, leading to “orphan” containers and configuration drift.

\n

The solution is Portainer Stacks. Stacks allow you to define your entire application architecture in a single Docker Compose specification, providing a centralized GUI to deploy, update, and scale related services as a single unit.

\n

Prerequisites

\n

\n
• A running Portainer Community Edition (CE) or Business Edition (BE) instance.
\n
• A Docker environment (Standalone or Swarm) connected as an Endpoint in Portainer.
\n
• A valid docker-compose.yml file or access to a Git repository containing one.
\n
• Administrative permissions within the Portainer environment to create and modify stacks.
\n

\n

Deploying a Stack via Web Editor

\n

\n
1. Navigate to Stacks in the left‑hand sidebar and click Add stack.
\n
2. Give the stack a unique name (e.g., monitoring-suite).
\n
3. Select the Web editor build method.
\n
4. Paste your YAML configuration. For example, a basic Nginx and Redis pair:
\n

\n

version: '3.8'\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - "8080:80"\n    depends_on:\n      - cache\n  cache:\n    image: redis:alpine

\n

\n
1. Click Deploy the stack. Portainer will pull the images and start the containers in the order defined by depends_on.
\n

\n

Implementing Git‑Based Continuous Deployment

\n

To avoid manual pasting, you can link a stack to a Git repository. This enables a “GitOps” workflow where pushing a change to your repository can trigger an update in Portainer.

\n

\n
1. In the Add stack menu, select Repository.
\n
2. Provide the Repository URL (HTTPS or SSH).
\n
3. Specify the Compose path (usually docker-compose.yml).
\n
4. Enable Automatic updates if you want Portainer to poll the repository for changes. You can choose between a polling interval or a webhook trigger.
\n
5. Click Deploy the stack.
\n

\n

Managing Environment Variables

\n

Hardcoding passwords or API keys in your YAML file is a security risk. Portainer Stacks provide an Environment variables section below the editor.

\n

\n
• Click Add environment variable.
\n
• Enter the key (e.g., DB_PASSWORD) and the value.
\n
• Reference these in your YAML using the ${VARIABLE_NAME} syntax.
\n

\n

These variables are injected into the containers at runtime, keeping sensitive data out of your version control system.

\n

Verification and Diagnostics

\n

After deployment, verify the health of your services using these checks:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Check	Expected Result	Action if Failed
Stack Dashboard	All services show a green “running” status.	Check the Logs icon for the specific container.
Network Connectivity	Services can communicate via service names (e.g., web can ping cache).	Verify the networks section of your Compose file.
Variable Injection	Run env inside the container shell to see the injected variables.	Check for typos in the Portainer Environment variable keys.

\n

Operational Risks and Recovery

\n

Risk: Service Downtime – Updating a stack via the GUI may trigger a full recreation of containers, causing brief unavailability.

\n

Risk: CLI Overwrites – Manual changes made to containers via Docker CLI will be overwritten the next time the stack is updated through Portainer.

\n

Rollback Procedure

\n

Since Portainer Stacks change the state of the Docker engine, use these steps to revert:

\n

\n
1. Revert Git Commit – If using Git, revert the commit in your repository and trigger a redeploy.
\n
2. Manual YAML Reversion – If using the Web Editor, paste the previous known‑working YAML configuration and click Update the stack.
\n
3. Full Purge – If the stack is corrupted, select the stack and click Remove. This deletes all associated containers and networks. Note: Volumes will remain unless explicitly deleted.
\n