vagrant-docker-swarm/README.md

# Docker Swarm Vagrant Cluster

A **production-ready** Docker Swarm cluster with 1 manager and 3 worker nodes for container orchestration and deployment.

## 🐳 Docker Swarm Features

- **1 Swarm Manager** - Cluster orchestration and management
- **3 Swarm Workers** - Container execution and scaling
- **Overlay Networking** - Secure multi-host container communication
- **Service Discovery** - Built-in DNS and load balancing
- **High Availability** - Automatic failover and service recovery
- **Portainer UI** - Web-based cluster management interface
- **Traefik** - Reverse proxy with automatic service discovery

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ swarm-manager   │    │ swarm-worker1   │    │ swarm-worker2   │    │ swarm-worker3   │
│ 192.168.56.10   │    │ 192.168.56.11   │    │ 192.168.56.12   │    │ 192.168.56.13   │
│                 │    │                 │    │                 │    │                 │
│ - Swarm Manager │    │ - Swarm Worker  │    │ - Swarm Worker  │    │ - Swarm Worker  │
│ - Portainer UI  │    │ - Container     │    │ - Container     │    │ - Container     │
│ - Traefik Proxy │    │   Execution     │    │   Execution     │    │   Execution     │
│ - Service       │    │ - Load          │    │ - Load          │    │ - Load          │
│   Discovery     │    │   Balancing     │    │   Balancing     │    │   Balancing     │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │                       │
         └───────────────────────┼───────────────────────┼───────────────────────┘
                                 │                       │
                    ┌─────────────┴───────────────────────┴─────────────┐
                    │              Docker Swarm Overlay Network         │
                    │              - Service Discovery                   │
                    │              - Load Balancing                      │
                    │              - Secure Communication               │
                    └─────────────────────────────────────────────────────┘
```

## 📋 Prerequisites

- **Vagrant** 2.2+
- **VirtualBox** 6.0+ or **libvirt** (KVM)
- **Ansible** 2.9+
- **2GB+ RAM** (512MB per machine + 1GB swap)
- **6GB+ free disk space**

## 🚀 Quick Start

1. **Start all machines:**
   ```bash
   make start
   ```

2. **Check status:**
   ```bash
   make status
   ```

3. **Access a machine:**
   ```bash
   make ssh-manager
   make ssh-worker1
   ```

## 🎛️ Management Commands

### Using Make
```bash
make start          # Start all machines
make stop           # Stop all machines
make destroy        # Destroy all machines
make status         # Show machine status
make ssh-manager     # Access swarm manager
make ssh-worker1     # Access swarm worker1
make ssh-worker2     # Access swarm worker2
make ssh-worker3     # Access swarm worker3
```

### Using Management Script
```bash
./manage.sh start           # Start all machines
./manage.sh stop            # Stop all machines
./manage.sh destroy         # Destroy all machines
./manage.sh status          # Show machine status
./manage.sh ssh swarm-manager  # Access swarm manager
./manage.sh ssh swarm-worker1 # Access swarm worker1
```

### Using Vagrant Directly
```bash
vagrant up                   # Start all machines
vagrant halt                 # Stop all machines
vagrant destroy -f           # Destroy all machines
vagrant status               # Show machine status
vagrant ssh swarm-manager    # Access swarm manager
vagrant ssh swarm-worker1    # Access swarm worker1
```

## 🌐 Network Configuration

- **Swarm Manager**: 192.168.56.10
- **Swarm Worker 1**: 192.168.56.11
- **Swarm Worker 2**: 192.168.56.12
- **Swarm Worker 3**: 192.168.56.13

All machines are connected via a private network and communicate through Docker Swarm overlay networking.

## 🔧 Machine Specifications

- **OS**: Debian 11 (Bullseye)
- **RAM**: 512MB per machine + 1GB swap
- **CPU**: 1 core per machine
- **Disk**: 8GB per machine

## 📁 Project Structure

```
test-vagrant/
├── Vagrantfile          # Debian Linux cluster configuration
├── manage.sh            # Management script
├── Makefile             # Make targets
├── inventory            # Ansible inventory file
├── setup-playbook.yml   # Setup playbook (dependencies, Python, swap)
├── deploy-playbook.yml  # Deployment playbook (apps, services)
├── README.md            # This file
└── .gitignore           # Git ignore rules
```

## 🛠️ Troubleshooting

### Common Issues

1. **Machines not starting:**
   ```bash
   vagrant status
   vagrant up --debug
   ```

2. **Network issues:**
   ```bash
   vagrant ssh host -c "ping 192.168.56.10"
   ```

3. **SSH issues:**
   ```bash
   vagrant ssh-config
   ```

### Useful Commands

```bash
# Check machine status
vagrant status

# View machine details
vagrant ssh-config

# Reload machines
vagrant reload

# Provision machines
vagrant provision
```

## 🐧 Debian Linux Notes

### **Package Management**
```bash
# Update package index
apt update

# Install packages
apt install package-name

# Search packages
apt search keyword
```

### **Common Debian Commands**
```bash
# Check system info
uname -a
cat /etc/os-release

# Check memory usage
free -m

# Check disk usage
df -h
```

## 🎭 Ansible Integration

### **Prerequisites**
```bash
# Install Ansible (on your host machine)
pip install ansible

# Or on Ubuntu/Debian
sudo apt install ansible
```

### **Ansible Commands**
```bash
# Test connectivity to all hosts
make ansible-ping

# Install dependencies (Python, tools, swap)
make ansible-setup

# Deploy applications and services
make ansible-deploy

# List all hosts
make ansible-list

# Gather system facts
make ansible-facts
```

### **Using Management Script**
```bash
# Test Ansible connectivity
./manage.sh ansible ping

# Install dependencies
./manage.sh ansible setup

# Deploy applications
./manage.sh ansible deploy
```

### **Direct Ansible Commands**
```bash
# Test connectivity
ansible all -i inventory -m ping

# Run setup playbook
ansible-playbook -i inventory setup-playbook.yml

# Run deployment playbook
ansible-playbook -i inventory deploy-playbook.yml

# Run on specific hosts
ansible-playbook -i inventory deploy-playbook.yml --limit machines

# Run with verbose output
ansible-playbook -i inventory deploy-playbook.yml -v
```

## 🚀 Next Steps

This is a bare-bones Debian setup. You can extend it by:

1. **Adding provisioning scripts** to install Debian packages
2. **Setting up networking** between machines
3. **Installing Docker** (Debian has excellent Docker support)
4. **Adding lightweight services** (nginx, redis, etc.)
5. **Setting up monitoring** with lightweight tools

## 📄 License

This project is licensed under the MIT License.

---

**Ultra-Lightweight Debian! 🐧⚡**