Skip to content
Infrastructure

Docker Swarm: From Desktop to Production-Ready Homelab

By Victor Da Luz
docker swarm homelab infrastructure traefik containers linux vm

I recently migrated my homelab from Docker Desktop to Docker Swarm with Linux VM workers—and it solved the stability issues I’d been dealing with. Docker Desktop is great for development, but it’s not designed for hands-off homelab workloads. When your services start going down randomly and nodes disappear from the cluster, you need something more reliable.

This article covers the migration process, the problems I encountered, and how I solved them. It’s based on real experience, not theoretical best practices.

Why Docker Desktop fails for hands-off homelab

Docker Desktop on macOS has known stability issues with Swarm mode. Here’s what I experienced:

  • Nodes going “Down”: Worker nodes would randomly disappear from the cluster
  • Service instability: Containers would restart unexpectedly
  • Resource contention: Docker Desktop competes with other macOS processes
  • File system issues: Bind mounts and volume access problems
  • Memory pressure: Docker Desktop’s VM can’t compete with native Linux performance

The final straw was when my Traefik reverse proxy started failing every few hours. Services would become unreachable, and I’d have to manually restart Docker Desktop to restore functionality. That’s not acceptable for a homelab that should run mostly hands-off.

The solution: Linux VM workers

I migrated to a proper Docker Swarm cluster with Linux VM workers. Here’s the architecture:

  • Manager: Raspberry Pi 4 - dedicated Swarm manager
  • Workers: Two Ubuntu Server 24.04 LTS VMs
  • Network: Dedicated VLAN for Swarm traffic (not necessary but I already had one for servers)
  • Storage: NAS for persistent volumes and backups

The key insight: Docker Swarm needs native Linux stability, specially for networking. The stability improvement was immediate.

The migration process

I used a phased approach to minimize downtime. Here’s what actually worked:

Phase 1: Prepare the infrastructure

Set up dedicated Linux VMs for Swarm workers. The process was straightforward - install Docker CE on Ubuntu Server and join the existing Swarm cluster.

Phase 2: Deploy Traefik with enhanced configuration

The Traefik stack became the foundation for all other services. Key improvements over Docker Desktop included proper health checks, resource constraints, network isolation, and persistent storage management.

Phase 3: External service proxying

One of the biggest advantages: Traefik can proxy services running outside Docker Swarm. This allowed me to gradually migrate services without rebuilding everything at once.

This approach let me:

  • Keep existing services running during migration
  • Test new services before switching over
  • Maintain zero-downtime deployments
  • Gradually move services to Docker Swarm

The backup strategy

I implemented a simple but effective backup approach. No complex tools needed - just standard Linux utilities with automated scheduling via systemd timers.

Key principles:

  • Simple tools: Use standard Linux utilities (tar, gzip)
  • Automated scheduling: systemd timers for reliability
  • Rolling retention: Keep recent backups, delete old ones
  • NAS storage: Leverage existing infrastructure

Lessons learned

The migration taught me several important lessons:

1. Docker Desktop is for development, not hands-off homelab

Docker Desktop’s VM layer creates too many failure points for services that need to run reliably. The stability improvement with native Linux was immediate.

2. Health checks are essential

Proper health checks prevent cascading failures. Every service now has health monitoring, and Traefik won’t route traffic to unhealthy containers.

3. External service proxying is powerful

You don’t need to migrate everything at once. Traefik’s file provider lets you proxy existing services while gradually moving them to Docker Swarm.

4. Simple backup strategies work best

Complex backup tools are overkill for homelab. Standard Linux utilities with proper scheduling provide reliable, maintainable backups.

5. Resource constraints matter

Docker Swarm’s placement constraints and resource limits prevent resource contention. Services now run where they should, with proper resource allocation.

The results

After the migration:

  • Stable services: No more random restarts
  • Better performance: Native Linux performance vs macOS VM
  • Proper monitoring: Health checks and logging
  • Reliable backups: Automated daily backups
  • Scalable architecture: Easy to add more workers

The homelab now runs mostly hands-off. Services stay up, backups run automatically, and I can deploy new services with confidence.

What’s next

The infrastructure is ready for expansion:

  • PostgreSQL cluster: Shared database for multiple services
  • Nextcloud: File storage and sharing
  • UniFi Controller: Network management
  • Additional services: Easy to deploy with the established patterns

The key insight: Docker Swarm with Linux workers provides the reliability that Docker Desktop can’t match. For hands-off homelab workloads, native Linux performance is essential.

The migration was worth the effort. The homelab is now stable and reliable.

Ready to Transform Your Career?

Let's work together to unlock your potential and achieve your professional goals.