File Organization:

/mnt/docker-configs/swarm/
├── database/
│   ├── master-db.yml          # PostgreSQL
│   ├── mariab-service.yml     # MariaDB
│   └── adminer.yml            # Database admin
├── traefik/
│   └── traefik-stack.yml      # Reverse proxy
├── authentication/
│   └── authentik-stack.yml    # Identity provider
├── applications/
│   ├── nextcloud-stack.yml
│   ├── paperless-stack.yml
│   ├── vikunja-stack.yml
│   └── bookstack-stack.yml
├── monitoring/
│   ├── uptime-kuma-stack.yml
│   └── homarr-service.yml
└── management/
    └── portainer-stack.yml

Standard Stack Structure:

# Version specification (optional but recommended)
services:
  service-name:
    image: image:tag
    environment:
      - VAR=value
    volumes:
      - volume_name:/container/path
    networks:
      - homelab
    deploy:
      replicas: 1
      placement:
        constraints: [node.hostname == p0]
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.service.rule=Host(`service.domain.me`)"

networks:
  homelab:
    external: true

volumes:
  volume_name:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/swarm-data/service/data

Deployment Commands and Verification

Deploy a Stack:

# Deploy with explicit configuration file
docker stack deploy -c /mnt/docker-configs/swarm/service/stack.yml stack-name

# Examples from your cluster:
docker stack deploy -c /mnt/docker-configs/swarm/traefik/traefik-stack.yml traefik
docker stack deploy -c /mnt/docker-configs/swarm/database/master-db.yml postgresql17
docker stack deploy -c /mnt/docker-configs/swarm/authentication/authentik-stack.yml auth

Verify Deployment:

# List all stacks
docker stack ls

# List services in a stack
docker stack services stack-name

# Check service status
docker service ls

# View service details
docker service inspect service-name

# Check service logs
docker service logs -f service-name

Stack Status Verification:

# Your current stacks should show:
STACKS          SERVICES        ORCHESTRATOR
adminer         1               Swarm
auth            3               Swarm
books           1               Swarm
homarr          1               Swarm
mariadb         1               Swarm
nextcloud       2               Swarm
paperless       2               Swarm
portainer       2               Swarm
postgresql17    1               Swarm
tracker-prod    1               Swarm
traefik         1               Swarm
uptime          1               Swarm
vikunja         1               Swarm

Update and Rollback Strategies

Update a Service:

# Update service image
docker service update --image new-image:tag service-name

# Update service with new configuration
docker stack deploy -c updated-stack.yml stack-name

# Force update (recreate containers)
docker service update --force service-name

# Update with rollback capability
docker service update --update-delay 10s --update-parallelism 1 service-name

Rollback Procedures:

# Rollback to previous version
docker service rollback service-name

# View update history
docker service ps service-name

# Rollback entire stack
docker stack deploy -c previous-stack.yml stack-name

Zero-Downtime Updates:

# Configure rolling updates in stack file
deploy:
  update_config:
    parallelism: 1
    delay: 10s
    failure_action: rollback
  rollback_config:
    parallelism: 1
    delay: 5s