mkswarm

CLI tool for bootstrapping and managing Docker Swarm clusters.

Install

pip install mkswarm

Usage

# Initialize a new Docker Swarm
mkswarm init -i ips.txt -m 192.168.1.1 -r 0.2 -o join.sh

# Run pending node joins via Docker SDK
mkswarm run 1

# Show swarm state
mkswarm status 1

# List all swarms
mkswarm list

# Regenerate join script from database
mkswarm reemit 1 -o new_join.sh

# Force-leave all nodes and destroy swarm
mkswarm destroy 1

IP File Format

Create a text file with one IPv4 address per line:

# Manager node
192.168.1.1

# Worker nodes
192.168.1.2
192.168.1.3
192.168.1.4

Token Encryption

Encrypt tokens at rest using Fernet:

# Generate a key
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# Use with mkswarm
export MKSWARM_KEY="your-generated-key"
mkswarm init -i ips.txt -m 192.168.1.1 -r 0.2 -o join.sh -k "$MKSWARM_KEY"

Proxy Support

Use SOCKS4, SOCKS5, or HTTP proxy:

mkswarm init -i ips.txt -m 192.168.1.1 -r 0.2 -o join.sh -p socks5://proxy:1080

TLS Support

Configure mutual TLS for Docker TCP connections:

mkswarm init -i ips.txt -m 192.168.1.1 -r 0.2 -o join.sh \
  --tls-cert client-cert.pem \
  --tls-key client-key.pem \
  --tls-ca ca.pem

CLI Options

Global Options

• --db FILE - SQLite database path (default: swarm.db)
• --verbose - Enable debug logging
• --quiet - Suppress warnings
• --log-file FILE - Append logs to file
• --dry-run - Preview actions without contacting Docker or writing files

Subcommands

• init - Bootstrap a new swarm
• run - Join pending nodes via Docker SDK
• status - Show swarm state
• list - List all swarms
• reemit - Regenerate join script from DB
• destroy - Force-leave all nodes

API

from mkswarm import SwarmDB, encrypt_token, decrypt_token, load_ips

# Database operations
db = SwarmDB("swarm.db")
swarm_id = db.create_swarm("192.168.1.1", "worker_token", "manager_token", 0.2, "192.168.1.1:2377", "join.sh")
swarm = db.get_swarm(swarm_id)
db.close()

# Token encryption
key = generate_key()  # Generate new key
encrypted = encrypt_token(token, key)
decrypted = decrypt_token(encrypted, key)

# IP validation
ip = parse_ipv4("192.168.1.1")
ips = load_ips("ips.txt")

Development

git clone https://github.com/daedalus/mkswarm.git
cd mkswarm
pip install -e ".[test]"

# run tests
pytest

# format
ruff format src/ tests/

# lint
ruff check src/ tests/

# type check
mypy src/

License

MIT License - see LICENSE file for details.