Deciding When to Use Portainer UI for Docker Compose Stacks in Swarm Mode

Decision and Constraints

You need to deploy a Docker Compose application to a Swarm cluster and want to know whether to use Portainer’s graphical interface or the Docker CLI. The decision hinges on three constraints:

• The target endpoint must be a Swarm mode cluster; deploying to a standalone engine will fail.
• All secrets, configs, or external files referenced in the compose file must already exist in the Swarm or be supplied externally, because Portainer does not create them automatically.
• You require a repeatable, auditable process that can be performed by team members who may not be comfortable with the CLI.

Options Comparison

Action	Portainer UI Steps	Underlying Docker Command	When to Use
Deploy a new stack	Stacks → Add stack → Provide name, choose docker-compose.yml (upload or Git), click Deploy	docker stack deploy -c <file> <stack-name>	First‑time deployment or when you want a clean start.
Update an existing stack	Select stack → Recreate/Update → Upload revised compose file → Enable “Prune” to remove services not in the new file → Deploy	docker stack deploy -c <file> <stack-name> --prune	Iterative changes (e.g., replica count, image tag) where you want obsolete services cleaned up.
Remove a stack	Select stack → Remove → Confirm	docker stack rm <stack-name>	De‑commissioning an application or tearing down a test environment.

Trade‑offs

Using Portainer’s UI provides:

• A visual overview of stack status, running containers, and resource usage.
• Reduced chance of typographical errors in long docker stack commands.
• Access control via Portainer roles, letting you grant stack‑management rights without giving full Docker daemon access.

Limitations compared with the CLI:

• Advanced Compose features such as profiles, configs defined inline, or custom deploy extensions are not exposed in the UI; you must use the CLI or Portainer API for those.
• The UI does not show the raw docker stack deploy output, making debugging of complex failures less straightforward.
• Batch operations across many stacks are faster with scripts than repeated UI clicks.

Implementation Steps (Deploy a Stack via UI)

1. Log in to Portainer with a user that has the “Stacks” management permission on the target endpoint.
2. Navigate to Endpoints → select your Swarm endpoint → confirm the environment shows “Docker Swarm”.
3. Go to Stacks → Add stack.
4. Fill in:
• Name: <YOUR_STACK_NAME> (e.g., webapp)
• Method: Choose Repository if your compose file is in Git, or Upload file and select your local docker-compose.yml.
• Environment variables (optional): add any ${VAR} placeholders used in the compose file.
5. Toggle Prune if you are updating an existing stack and want to remove services not present in the new file.
6. Click Deploy the stack.
7. After deployment, open the stack’s detail page to see the list of services and their desired/replica counts.

Verification and Practical Checks

To confirm the operation succeeded, you can either rely on Portainer’s status indicators or run a quick CLI check:

• In Portainer, the stack should appear with a status of Running and each service should show the expected number of running containers.
• From a terminal with access to the Swarm manager, run:

docker stack services <YOUR_STACK_NAME>

You should see a table listing each service, its replica count, and the image used. If the replica count matches what you specified in the compose file, the deployment is correct.

Limitations and How to Check Them

Portainer’s UI does not automatically create secrets or configs. If your compose file references a secret like:

secrets:
  db_password:
    external: true

You must first create that secret in the Swarm:
echo "mysecret" | docker secret create db_password -

After creating the secret, repeat the stack deployment steps. You can verify the secret is attached by inspecting a service:
docker service inspect --format '{{ .Template.Spec.Secrets }}' <YOUR_STACK_NAME>_db

If the UI reports an error about a missing secret, the CLI command above will confirm whether the secret exists.
Rollback Considerations
Only the Update operation changes the state of a running stack. To rollback a problematic update, you can redeploy the previous known‑good compose file (without prune) or use:
docker stack rm <YOUR_STACK_NAME>
docker stack deploy -c <previous-compose.yml> <YOUR_STACK_NAME>

Always keep a copy of the last working compose file in version control before performing an update.