Installing Alpine Linux for Docker Swarm: Complete Cluster Setup Guide

I’ll show you how to set up Alpine Linux specifically for Docker Swarm clusters. After managing container infrastructure for years, I’ve found Alpine’s minimal footprint makes it perfect for Swarm nodes - you just need to configure it properly.

Introduction

Docker Swarm is great for orchestrating containers across multiple machines, but your choice of host OS matters a lot. Alpine Linux hits the sweet spot - it’s lightweight, secure, and has everything Docker needs without the bloat.

I’ve been running Swarm clusters on Alpine for production workloads, and the combination is rock solid. The small attack surface and efficient resource usage make it ideal for container hosts.

Why You Need This

• Minimize resource overhead on cluster nodes
• Reduce security attack surface in production
• Create consistent, reproducible cluster deployments
• Optimize container performance and density

Prerequisites

You’ll need these things first:

• Multiple servers or VMs (minimum 3 for HA)
• Network connectivity between all nodes
• Basic understanding of Docker and containers
• SSH access to all target machines

Step 1: Prepare Alpine Linux Base Installation

Install Minimal Alpine System

Let’s start with a clean Alpine installation optimized for containers.

What we’re doing: Installing Alpine with only essential packages for Docker Swarm.

# Boot from Alpine ISO and run setup
setup-alpine

# During setup, choose these options:
# - Keyboard layout: us
# - Hostname: swarm-node-01 (increment for each node)
# - Network: Configure static IP
# - Root password: Strong password
# - Timezone: Your timezone
# - Proxy: none
# - SSH server: openssh
# - Disk: sys (full installation)

Post-installation configuration:

# Update package repositories
apk update && apk upgrade

# Install essential packages
apk add curl wget nano htop

# Enable services for boot
rc-update add networking boot
rc-update add sshd default

Code explanation:

• setup-alpine: Interactive installer for Alpine Linux
• apk update && apk upgrade: Gets latest packages and security updates
• rc-update add: Enables services to start automatically on boot

Configure Network Settings

What we’re doing: Setting up static networking for reliable cluster communication.

# Edit network configuration
nano /etc/network/interfaces

Network configuration example:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    dns-nameservers 8.8.8.8 8.8.4.4
    dns-search localdomain

Configure hostname and hosts file:

# Set hostname
echo "swarm-node-01" > /etc/hostname

# Edit hosts file for cluster nodes
nano /etc/hosts

Hosts file example:

127.0.0.1    localhost
192.168.1.10 swarm-node-01
192.168.1.11 swarm-node-02
192.168.1.12 swarm-node-03

# Add all your planned Swarm nodes here

Tip: I always use static IPs for Swarm nodes. DHCP can cause headaches when nodes restart and get different addresses.

Step 2: Install and Configure Docker

Install Docker Engine

What we’re doing: Installing Docker with Alpine’s optimized package.

# Install Docker package
apk add docker docker-compose

# Add Docker to default runlevel
rc-update add docker default

# Start Docker service
service docker start

# Add user to docker group (optional)
addgroup $USER docker

Code explanation:

• apk add docker: Installs Docker engine optimized for Alpine
• rc-update add docker default: Enables Docker to start on boot
• addgroup $USER docker: Allows non-root user to run Docker commands

Configure Docker Daemon

What we’re doing: Optimizing Docker settings for Swarm cluster operation.

# Create Docker daemon configuration
mkdir -p /etc/docker
nano /etc/docker/daemon.json

Docker daemon configuration:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "exec-opts": ["native.cgroupdriver=cgroupfs"],
  "live-restore": true,
  "userland-proxy": false,
  "experimental": false,
  "metrics-addr": "0.0.0.0:9323",
  "hosts": ["unix:///var/run/docker.sock"]
}

Configuration explanation:

• log-opts: Prevents log files from consuming too much disk space
• storage-driver: Uses overlay2 for better performance
• live-restore: Keeps containers running during Docker daemon restarts
• metrics-addr: Enables metrics collection for monitoring

Verify Docker Installation

What we’re doing: Testing Docker functionality before proceeding with Swarm setup.

# Check Docker version
docker version

# Test container functionality
docker run --rm hello-world

# Check Docker system info
docker system info

Expected Output:

Client:
 Version:           20.10.16
 API version:       1.41
 Go version:        go1.18.3
 Git commit:        aa7e414
 Built:             Thu Jul  7 14:08:51 2022
 OS/Arch:           linux/amd64

Server:
 Engine:
  Version:          20.10.16
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.18.3

Step 3: Configure Firewall for Swarm

Set Up iptables Rules

What we’re doing: Opening necessary ports for Docker Swarm cluster communication.

# Install iptables
apk add iptables ip6tables

# Create firewall script for Swarm
nano /etc/iptables/swarm-rules.sh

Swarm firewall rules:

#!/bin/sh
# Docker Swarm firewall configuration

# Clear existing rules
iptables -F
iptables -X

# Set default policies
iptables -P INPUT DROP
iptables -P FORWARD ACCEPT
iptables -P OUTPUT ACCEPT

# Allow loopback
iptables -A INPUT -i lo -j ACCEPT

# Allow established connections
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# SSH access
iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# Docker Swarm ports
iptables -A INPUT -p tcp --dport 2377 -s 192.168.1.0/24 -j ACCEPT  # Cluster management
iptables -A INPUT -p tcp --dport 7946 -s 192.168.1.0/24 -j ACCEPT  # Node communication
iptables -A INPUT -p udp --dport 7946 -s 192.168.1.0/24 -j ACCEPT  # Node communication
iptables -A INPUT -p udp --dport 4789 -s 192.168.1.0/24 -j ACCEPT  # Overlay networks

# Allow Docker bridge traffic
iptables -A INPUT -i docker0 -j ACCEPT
iptables -A INPUT -i docker_gwbridge -j ACCEPT

# Application ports (adjust as needed)
iptables -A INPUT -p tcp --dport 80 -j ACCEPT   # HTTP
iptables -A INPUT -p tcp --dport 443 -j ACCEPT  # HTTPS

# Save and apply rules
iptables-save > /etc/iptables/rules-save

Code explanation:

• --dport 2377: Cluster management communications (manager nodes only)
• --dport 7946: Communication among nodes (TCP and UDP)
• --dport 4789: Overlay network traffic (UDP)
• -s 192.168.1.0/24: Restricts access to your cluster subnet

Make Firewall Persistent

What we’re doing: Ensuring firewall rules survive reboots.

# Make script executable
chmod +x /etc/iptables/swarm-rules.sh

# Apply the rules
/etc/iptables/swarm-rules.sh

# Create init script for startup
nano /etc/init.d/iptables-swarm

Init script content:

#!/sbin/openrc-run

name="iptables-swarm"
command="/sbin/iptables-restore"
command_args="< /etc/iptables/rules-save"

depend() {
    need net
    before docker
}

Enable firewall service:

# Make init script executable
chmod +x /etc/init.d/iptables-swarm

# Enable service
rc-update add iptables-swarm default

Step 4: Initialize Docker Swarm Cluster

Set Up Manager Node

What we’re doing: Creating the Swarm cluster with the first manager node.

# Initialize Swarm on first node (manager)
docker swarm init --advertise-addr 192.168.1.10

# Get join tokens for other nodes
docker swarm join-token manager
docker swarm join-token worker

Expected Output:

Swarm initialized: current node (abc123def456) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-xxx-yyy 192.168.1.10:2377

To add a manager to this swarm, run 'docker swarm join-token manager'

Add Additional Nodes

What we’re doing: Joining other Alpine nodes to the Swarm cluster.

# On second manager node (for HA)
docker swarm join --token SWMTKN-1-manager-token-here 192.168.1.10:2377

# On worker nodes
docker swarm join --token SWMTKN-1-worker-token-here 192.168.1.10:2377

# Verify cluster status from manager
docker node ls

Cluster status output:

ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS
abc123def456 *                swarm-node-01   Ready     Active         Leader
def456ghi789                  swarm-node-02   Ready     Active         Reachable
ghi789jkl012                  swarm-node-03   Ready     Active

Step 5: Configure Swarm for Production

Set Up Node Labels

What we’re doing: Adding labels to nodes for workload placement.

# Label nodes by role and capabilities
docker node update --label-add role=frontend swarm-node-01
docker node update --label-add role=backend swarm-node-02
docker node update --label-add role=database swarm-node-03

# Add environment labels
docker node update --label-add env=production swarm-node-01
docker node update --label-add zone=zone-a swarm-node-01

# Check node labels
docker node inspect swarm-node-01 --pretty

Code explanation:

• --label-add role=frontend: Designates node for frontend workloads
• Labels help with service placement and resource management
• You can create custom labels for your specific needs

Configure Resource Limits

What we’re doing: Setting up resource constraints for better cluster management.

# Update Docker daemon for resource management
nano /etc/docker/daemon.json

Enhanced daemon configuration:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "exec-opts": ["native.cgroupdriver=cgroupfs"],
  "live-restore": true,
  "userland-proxy": false,
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  },
  "max-concurrent-downloads": 10,
  "max-concurrent-uploads": 5
}

Restart Docker with new configuration:

# Restart Docker service
service docker restart

# Verify configuration
docker system info | grep -A 10 "Security"

Practical Examples

Example 1: Deploy Sample Application

What we’re doing: Testing the Swarm cluster with a real application deployment.

# Create a simple web service
docker service create \
  --name web-app \
  --replicas 3 \
  --publish 8080:80 \
  --constraint 'node.labels.role==frontend' \
  nginx:alpine

# Check service status
docker service ls
docker service ps web-app

# Scale the service
docker service scale web-app=5

# Update the service
docker service update --image nginx:1.21-alpine web-app

Code explanation:

• --replicas 3: Runs 3 instances of the service
• --publish 8080:80: Maps host port 8080 to container port 80
• --constraint: Places service only on nodes with specific labels
• docker service scale: Changes number of running replicas

Example 2: Create Overlay Network

What we’re doing: Setting up isolated networking for multi-service applications.

# Create custom overlay network
docker network create \
  --driver overlay \
  --subnet 10.10.0.0/16 \
  --attachable \
  app-network

# Deploy services on custom network
docker service create \
  --name web-frontend \
  --network app-network \
  --replicas 2 \
  nginx:alpine

docker service create \
  --name api-backend \
  --network app-network \
  --replicas 3 \
  node:alpine

# Test network connectivity
docker service exec web-frontend.1 ping api-backend

Troubleshooting

Common Swarm Issues

Problem: Nodes showing as “Down” in cluster Solution: Check network connectivity and firewall rules

# Check node status
docker node ls

# Inspect problematic node
docker node inspect node-name

# Check Docker logs
journalctl -u docker.service -f

# Test network connectivity
ping swarm-node-02
telnet swarm-node-02 2377

Service Deployment Problems

Problem: Services not starting or failing health checks Solution: Debug service logs and constraints

# Check service logs
docker service logs web-app

# Inspect service configuration
docker service inspect web-app

# Check available resources
docker node ls
docker system df

# Force service update
docker service update --force web-app

Network Connectivity Issues

Problem: Services can’t communicate across nodes Solution: Verify overlay network configuration

# List networks
docker network ls

# Inspect overlay network
docker network inspect ingress

# Check iptables rules
iptables -L -n | grep 4789

# Test container-to-container connectivity
docker exec -it container-id ping target-service

Best Practices

1. High Availability Setup:

   # Use odd number of managers (3 or 5)
   # Keep managers on separate physical hosts
   # Regular backup of Swarm state
   docker swarm ca --rotate

2. Security Hardening:

   • Use TLS certificates for cluster communication
   • Regularly rotate join tokens
   • Implement proper RBAC with secrets management
   • Monitor cluster access logs

3. Resource Management:

   • Set memory and CPU limits on services
   • Use placement constraints effectively
   • Monitor node resource usage
   • Plan for auto-scaling scenarios

Verification

To verify your Swarm cluster is working correctly:

# Check cluster health
docker system info | grep Swarm
docker node ls

# Test service deployment
docker service create --name test --replicas 2 alpine ping google.com
docker service ps test

# Verify networking
docker network ls | grep overlay

# Clean up test service
docker service rm test

Wrapping Up

You just set up a production-ready Docker Swarm cluster on Alpine Linux:

• Installed minimal Alpine systems optimized for containers
• Configured Docker with proper settings for clustering
• Set up secure networking and firewall rules
• Created a multi-node Swarm cluster with HA managers
• Configured resource management and node labeling

This setup gives you a lightweight, secure foundation for container orchestration. Alpine’s minimal footprint means more resources for your applications, and the robust networking makes it perfect for production workloads. I’ve been running clusters like this for years and they just work.