Solved: I built a CLI tool to deploy to Docker Swarm like it’s Vercel (Secrets rotation, Multi-env)

🚀 Executive Summary

TL;DR: Docker Swarm deployments often struggle with manual errors, complex secrets rotation, and fragmented multi-environment configurations, leading to poor developer experience. A custom CLI tool offers a Vercel-like solution by abstracting these complexities, providing single-command deployments, automated secrets management, and easy rollbacks for streamlined operations.

🎯 Key Takeaways

• Docker Swarm deployments without dedicated tooling suffer from manual errors, fragmented configuration, complex secrets management, and poor developer experience.
• Manual scripting with docker-compose.yml offers control but is prone to error, lacks scalability, and complicates secrets rotation and rollbacks.
• CI/CD pipelines automate Docker Swarm deployments, improving consistency and integrating with secret managers, but introduce higher initial setup complexity.
• A dedicated CLI tool provides a Vercel-like developer experience for Docker Swarm, offering single-command deployments, automated multi-environment configuration, built-in secrets rotation, and simplified rollbacks.

Building a robust deployment pipeline for Docker Swarm, especially when aiming for Vercel-like developer experience, secrets rotation, and multi-environment support, can be challenging. This post explores common pain points and offers three distinct solutions, culminating in a custom CLI tool approach.

The Challenge: Simplifying Docker Swarm Deployments for Modern DevOps

Symptoms of Complex Docker Swarm Workflows

While Docker Swarm provides a lightweight orchestration solution, achieving a streamlined, developer-friendly deployment experience often requires significant custom scripting. Without dedicated tools, IT professionals frequently encounter the following issues:

• Manual and Error-Prone Deployments: Relying on manual docker stack deploy commands, often with environment-specific overrides or file modifications, increases the risk of human error and slows down release cycles.
• Fragmented Configuration Management: Managing distinct environment variables, network settings, and resource limits for development, staging, and production can lead to configuration drift and inconsistent deployments.
• Secrets Management Overhead: Handling Docker Swarm secrets – their creation, updates, and especially secure rotation – becomes a significant operational burden, often involving manual steps or complex scripting to avoid downtime.
• Lack of Atomic Deployments and Easy Rollbacks: Without a higher-level abstraction, ensuring zero-downtime deployments and quickly rolling back to a previous stable version upon failure is difficult to achieve consistently.
• Poor Developer Experience (DX): Developers often face a steep learning curve or cumbersome processes to get their applications deployed, contrasting sharply with the “just push and it deploys” simplicity offered by platforms like Vercel or Netlify.

These symptoms collectively highlight a need for more sophisticated tooling to elevate Docker Swarm deployments beyond basic orchestration into a truly efficient and enjoyable experience.

Solution 1: Manual Orchestration with Scripts and Docker Compose

Approach

The most straightforward (and often initial) approach involves leveraging Docker Compose files combined with shell scripts. This method allows you to define your services and dependencies once in a docker-compose.yml and then use scripts to inject environment-specific variables and secrets before deploying to Swarm.

• Docker Compose for Service Definition: A single docker-compose.yml defines the application’s services, networks, and volumes.
• Shell Scripts for Environment Customization: Bash or similar scripts are used to set environment variables, select image tags, and handle secrets based on the target environment.
• Manual Secrets Handling: Secrets are typically managed as files on the Swarm manager or passed directly to docker secret create/update commands within scripts.

Example: Multi-environment docker-compose.yml

Here’s how a generic docker-compose.yml might look, designed to be flexible with environment variables:

version: '3.8'

services:
  webapp:
    image: myapp:${IMAGE_TAG:-latest}
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - API_KEY=${API_KEY}
    secrets:
      - app_secret

secrets:
  app_secret:
    external: true

Example: Deployment Script (deploy.sh)

A simple shell script can then manage the environment-specific configurations:

#!/bin/bash

# Usage: ./deploy.sh  

ENV=$1
TAG=$2

if [ -z "$ENV" ] || [ -z "$TAG" ]; then
  echo "Usage: $0  "
  echo "Example: $0 dev 1.0.0-rc1"
  echo "Example: $0 prod 1.0.0"
  exit 1
fi

STACK_NAME="myapp-${ENV}"
COMPOSE_FILE="docker-compose.yml"

echo "Deploying to ${ENV} environment with image tag ${TAG}..."

# --- Environment-specific configuration ---
case "$ENV" in
  dev)
    export DATABASE_URL="mongodb://dev-db:27017/dev_data"
    export API_KEY="dev_api_key_123"
    export IMAGE_TAG="${TAG}-dev"
    # Ensure dev secret exists or create/update it
    if ! docker secret inspect app_secret_dev &>/dev/null; then
      echo "Creating 'app_secret_dev' for development."
      docker secret create app_secret_dev ./secrets/dev/app_secret.txt
    else
      echo "Updating 'app_secret_dev' for development."
      docker secret update app_secret_dev ./secrets/dev/app_secret.txt
    fi
    ;;
  prod)
    export DATABASE_URL="mongodb://prod-db:27017/prod_data"
    export API_KEY="prod_api_key_abc"
    export IMAGE_TAG="${TAG}"
    # Ensure prod secret exists or create/update it
    if ! docker secret inspect app_secret_prod &>/dev/null; then
      echo "Creating 'app_secret_prod' for production."
      docker secret create app_secret_prod ./secrets/prod/app_secret.txt
    else
      echo "Updating 'app_secret_prod' for production."
      docker secret update app_secret_prod ./secrets/prod/app_secret.txt
    fi
    ;;
  *)
    echo "Error: Unknown environment '$ENV'. Must be 'dev' or 'prod'."
    exit 1
    ;;
esac

# Link the environment-specific secret to the generic 'app_secret' name in the Compose file
# This assumes the docker-compose.yml refers to 'app_secret' and we're mapping it dynamically
# NOTE: Docker Compose doesn't directly support dynamic secret naming inside the file
# for external secrets that are part of the stack. A common workaround is to have
# different compose files per environment or use a tool to generate the compose file.
# For simplicity in this example, we assume `app_secret` in the compose file
# is meant to be the environment-specific one.
# A more robust approach would be to generate the compose file.

# A common pattern for secrets is to name them explicitly per environment in Docker Swarm
# and then use a compose file specific to that environment which references the correct secret.
# For example, in dev, `app_secret` refers to `app_secret_dev`.
# This script would need to dynamically generate a compose file or use `sed` to replace.
# For now, let's assume `app_secret` is pre-created as the correct environment secret.
# This part of secrets management is where manual scripting becomes unwieldy.

# For this example, let's simplify and assume `app_secret` is created manually *before* the script
# and the stack reference aligns. Or that we use a tool to generate the compose file.
# A more realistic approach would be to update the compose file on the fly with `sed` or `envsubst`.

# Using `envsubst` to replace variables in a template compose file
# (Requires `gettext` package on most systems)
envsubst < ${COMPOSE_FILE}.template > ${COMPOSE_FILE}

# Deploy the stack
echo "Running: docker stack deploy -c ${COMPOSE_FILE} --with-registry-auth ${STACK_NAME}"
docker stack deploy -c ${COMPOSE_FILE} --with-registry-auth ${STACK_NAME}

echo "Deployment to ${ENV} finished."

Pros and Cons of Manual Scripting

• Pros: Low initial complexity, full control, no external tools required beyond Docker.
• Cons: Prone to human error, difficult to scale, complex secrets rotation, no built-in rollbacks, poor developer experience.

Solution 2: CI/CD Pipelines with Orchestration Tools

Approach

Integrating Docker Swarm deployments into a Continuous Integration/Continuous Deployment (CI/CD) pipeline automates many manual steps, improves consistency, and provides better oversight. Tools like GitLab CI, GitHub Actions, Jenkins, or Azure DevOps can orchestrate the entire process, from building images to deploying services.

• Automated Builds and Pushes: The CI/CD pipeline builds Docker images and pushes them to a registry.
• Environment-Specific Variables: CI/CD platforms securely store environment variables and secrets, injecting them at deployment time.
• Secrets Manager Integration: Pipelines can integrate with dedicated secret management solutions (e.g., HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) for more robust secret handling and rotation.
• Orchestrated Deployment: The pipeline executes docker stack deploy commands, often targeting remote Swarm managers.

Example: GitLab CI (.gitlab-ci.yml)

This example demonstrates deploying to a production Swarm environment using GitLab CI, assuming a Swarm manager IP is available as a CI variable.

stages:
  - build
  - deploy

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: "" # Disable TLS for dind service

.build_template: &build_definition
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    - docker build -t "$CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY/$CI_PROJECT_PATH:$CI_COMMIT_SHORT_SHA"

build_image:
  <<: *build_definition
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^(feature|bugfix)\/.+$/

deploy_production:
  stage: deploy
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: "" # Disable TLS for dind service
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    # Ensure Docker context for Swarm manager is set up
    # SWARM_MANAGER_HOST must be a CI/CD variable pointing to your Swarm manager's IP/hostname
    - docker context create swarm-prod-context --docker "host=$SWARM_MANAGER_HOST" || true # Create if not exists
    - docker context use swarm-prod-context
  script:
    # Fetch environment variables and secrets securely from GitLab CI/CD variables
    - export DATABASE_URL="$PROD_DATABASE_URL"
    - export API_KEY="$PROD_API_KEY"
    - export IMAGE_TAG="$CI_COMMIT_SHORT_SHA"

    # Assume docker-compose.yml is prepared to use these variables,
    # or use `envsubst` with a template compose file.
    # Example using a template:
    - envsubst < docker-compose.prod.yml.template > docker-compose.prod.yml

    # Secret rotation integration (pseudo-code)
    # This would typically involve an external secret manager like Vault
    # - vault login -method=jwt role=gitlab-ci jwt=$CI_JOB_JWT
    # - NEW_APP_SECRET=$(vault kv get -field=app_secret secret/myapp/prod/latest)
    # - echo "$NEW_APP_SECRET" | docker secret update app_secret_prod -

    - docker stack deploy -c docker-compose.prod.yml --with-registry-auth myapp-prod
  environment:
    name: production
    url: https://myapp.prod.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Secrets Rotation Considerations

Within a CI/CD pipeline, secrets rotation can be automated by:

• Integrating with Secret Managers: Use tools like HashiCorp Vault. The pipeline can authenticate with Vault, fetch new secrets, and then update Docker Swarm secrets using docker secret update. Vault can also manage secret leases and automatic rotation.
• Triggering External Scripts: The pipeline can trigger an external script or webhook that performs the secret rotation on the Swarm manager and updates the Docker Swarm secret.

The key is to ensure that the secret manager has the necessary permissions and that the pipeline can securely retrieve the updated secret content.

Pros and Cons of CI/CD Pipelines

• Pros: Automation, consistency, traceability, robust secret management integration, better auditing, supports complex workflows.
• Cons: Higher initial setup complexity, requires a CI/CD platform, potential for “pipeline as a script” anti-pattern if not well-designed, less immediate feedback for developers compared to a dedicated CLI.

Solution 3: The Dedicated CLI Tool Approach (Vercel-like DX)

Inspired by Vercel/Netlify DX

The ideal solution for many teams is a dedicated command-line interface (CLI) tool that abstracts away the complexities of Docker Swarm, offering a Vercel-like developer experience. This approach emphasizes simplicity, speed, and reliability from the developer’s perspective while handling the underlying DevOps challenges. The Reddit post title “I built a CLI tool to deploy to Docker Swarm like it’s Vercel” directly points to this solution.

• Single Command Deployment: Developers can deploy with a single command, often just deploy.
• Automated Environment Variable Injection: The tool handles environment-specific configuration based on a simple project configuration.
• Built-in Secrets Management & Rotation: Integrates robust secrets handling, including creation, updates, and rotation, directly into the deployment workflow.
• Atomic Updates and Easy Rollbacks: The tool ensures zero-downtime deployments and provides simple commands for rollbacks to previous versions.

Core Functionality (Hypothetical Tool)

Such a CLI tool would typically:

• Read project and environment configurations from a central file (e.g., .swarmcli.yml).
• Dynamically generate a docker-compose.yml file tailored for the target environment, injecting correct image tags, environment variables, and secret references.
• Manage Docker Swarm secrets: create, update, and rotate them using content either provided directly or generated by a specified script.
• Execute docker stack deploy commands against the configured Swarm manager.
• Track deployments for easy rollback capabilities.

Example: .swarmcli.yml (Hypothetical Configuration)

A YAML configuration file would define environments, variables, and services for the tool:

project: my-app-service
docker_registry: my-registry.example.com/myapp

environments:
  dev:
    stack_name: my-app-dev
    manager_host: dev-swarm-manager.example.com:2376
    variables:
      DATABASE_URL: mongodb://dev-db:27017/dev_data
    secrets:
      - name: API_KEY_SECRET
        path: secrets/dev/api_key.txt # Path to file containing the secret value
      - name: JWT_SECRET
        path: secrets/dev/jwt_secret.txt
  prod:
    stack_name: my-app-prod
    manager_host: prod-swarm-manager.example.com:2376
    variables:
      DATABASE_URL: mongodb://prod-db:27017/prod_data
    secrets:
      - name: API_KEY_SECRET
        path: secrets/prod/api_key.txt
        rotate_command: ./scripts/rotate_prod_api_key.sh # Script to generate new secret content
      - name: JWT_SECRET
        path: secrets/prod/jwt_secret.txt
        rotate_command: ./scripts/rotate_prod_jwt_secret.sh

services:
  webapp:
    image_name: webapp
    build_path: .
    ports:
      - "80:80"
    environment:
      - NODE_ENV=${ENV_NAME} # ENV_NAME is automatically provided by the CLI (e.g., 'dev', 'prod')
    secrets:
      - source: API_KEY_SECRET
        target: API_KEY_IN_APP
      - source: JWT_SECRET
        target: JWT_SECRET_IN_APP

Example: CLI Commands (Hypothetical)

The tool would then expose simple commands:

# Build and deploy to development
swarmcli deploy --env dev --tag 1.0.0

# Deploy a specific tag to production
swarmcli deploy --env prod --tag 1.0.0

# Promote a successful dev deployment (e.g., re-using same image tag)
# The CLI would internally ensure the image exists and then deploy it to the new environment
swarmcli promote --from dev --to prod --tag 1.0.0

# Rotate a specific secret for production
swarmcli secret rotate --env prod API_KEY_SECRET

# Rollback production to the previous successful deployment
swarmcli rollback --env prod

# Show current deployments and their status
swarmcli status --env prod

Key Features and Benefits

• Simplified Deployment Workflow: One-command deployments drastically reduce complexity and error rates for developers.
• Automated Multi-Environment Configuration: Handles environment variables and secrets seamlessly based on the chosen target.
• Robust Secrets Management: Provides built-in mechanisms for creating, updating, and rotating Docker Swarm secrets, potentially integrating with external secret generation scripts.
• Versioned Deployments and Rollbacks: The tool can keep track of deployments, enabling quick and reliable rollbacks to previous stable versions.
• Enhanced Developer Experience: Mimics the ease of use found in platforms like Vercel, allowing developers to focus on code rather than infrastructure specifics.
• Zero-Downtime Deployments: By abstracting docker stack deploy and potentially adding pre/post-deployment hooks, the tool can ensure smooth updates.

Solution Comparison: Manual vs. CI/CD vs. Dedicated CLI

Feature	Manual Scripts	CI/CD Pipeline	Dedicated CLI Tool
Ease of Use (Developer)	Low	Medium (after initial setup)	High
Secrets Management	Manual/Basic scripting	Integrated with secret managers	Automated, built-in rotation
Multi-Environment Config	Script-driven, prone to error	Managed by pipeline variables	Declarative, built-in
Atomic Deployments	Difficult to achieve	Achievable with careful design	Built-in functionality
Rollbacks	Manual, complex	Possible, but requires setup	Simple command
Developer Experience (DX)	Poor	Good (for automated aspects)	Excellent
Initial Setup Complexity	Low	High	Medium (building/configuring tool)
Scalability	Low	High	High

Conclusion: Choosing Your Path to Streamlined Docker Swarm Deployments

Each solution offers distinct advantages, and the “best” choice depends on your team’s specific needs, size, and existing infrastructure:

• Manual Scripts: Suitable for small projects or early-stage development where quick iterations and minimal overhead are prioritized over robust automation. It quickly becomes unsustainable as projects grow.
• CI/CD Pipelines: An excellent choice for established teams needing comprehensive automation, strong governance, and integration with a wider ecosystem of tools (testing, monitoring, security scans). It requires significant upfront investment in pipeline configuration.
• Dedicated CLI Tool: The ideal solution for teams prioritizing developer experience, aiming for Vercel-like simplicity, and needing robust, opinionated handling of Docker Swarm specifics like secrets and multi-environment deployments. While it requires custom development or adopting a specialized third-party tool, the long-term benefits in terms of efficiency and DX are substantial.

By investing in a dedicated CLI tool, inspired by modern deployment platforms, you can transform Docker Swarm deployments from a complex operational challenge into a seamless, developer-centric workflow, unlocking greater agility and focus for your engineering teams.

---

👉 Read the original article on TechResolve.blog

---

☕ Support my work

If this article helped you, you can buy me a coffee:

👉 https://buymeacoffee.com/darianvance