Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » Orchestrating Microservices with Docker Swarm and Laravel: A High-Availability Pattern

Orchestrating Microservices with Docker Swarm and Laravel: A High-Availability Pattern

Docker Swarm: The Foundation for High Availability

Docker Swarm provides a native clustering and orchestration solution for Docker containers. Its simplicity and tight integration with the Docker API make it an excellent choice for achieving high availability and scalability for microservices without the steep learning curve of more complex orchestrators. We’ll leverage Swarm’s declarative service model to define our application’s desired state, ensuring that Swarm continuously works to maintain that state.

The core concept in Swarm is the ‘service’. A service defines a set of tasks (container instances) that run on the Swarm nodes. Swarm manager nodes schedule these tasks across worker nodes. For high availability, we’ll define multiple replicas for each service. If a container fails, Swarm automatically starts a new one to replace it. Load balancing is also built-in, distributing incoming traffic across all healthy replicas of a service.

Setting Up a Docker Swarm Cluster

A minimal Swarm cluster requires at least one manager node and one worker node. For production, we recommend multiple manager nodes for fault tolerance. Here’s how to initialize a Swarm on a manager node and join worker nodes.

Initializing the Swarm Manager

On your designated manager node, run:

docker swarm init --advertise-addr

This command initializes the Swarm and outputs a command to join worker nodes. Note the token and the manager’s IP address. For a multi-manager setup, you would promote other nodes to managers later.

Joining Worker Nodes

On each worker node, execute the command provided by docker swarm init:

docker swarm join --token  :2377

Verify the cluster status from the manager node:

docker node ls

Defining Laravel Microservices with Docker Compose

We’ll define our Laravel microservices using Docker Compose. This allows us to specify the image, ports, environment variables, and dependencies for each service. Swarm can then deploy these Compose files directly.

Example: A Simple API Service

Let’s consider a basic Laravel API service. We’ll need a Dockerfile to build our application image.

# Dockerfile for Laravel API Service
FROM php:8.2-fpm

WORKDIR /var/www/html

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libssl-dev \
    libonig-dev \
    libzip-dev \
    libicu-dev \
    libxslt1-dev \
    libzip-dev \
    zip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd \
    && docker-php-ext-install pdo pdo_mysql zip intl opcache bcmath sockets

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Copy application code
COPY . .

# Install dependencies
RUN composer install --no-dev --optimize-autoloader

# Permissions
RUN chown -R www-data:www-data storage bootstrap/cache
RUN chmod -R 775 storage bootstrap/cache

# Expose port
EXPOSE 9000

And a docker-compose.yml file to define the service for Swarm:

version: '3.8'

services:
  api:
    image: your-dockerhub-username/laravel-api:latest
    ports:
      - "80:80" # Map host port 80 to container port 80 (for Nginx/Apache)
    environment:
      APP_ENV: production
      APP_DEBUG: false
      DB_HOST: database
      DB_PORT: 3306
      DB_DATABASE: mydatabase
      DB_USERNAME: user
      DB_PASSWORD: password
    volumes:
      - .:/var/www/html # For development, remove for production
    deploy:
      replicas: 3 # Ensure 3 instances are running for HA
      restart_policy:
        condition: on-failure
      update_config:
        parallelism: 2
        delay: 10s
    networks:
      - app-network

networks:
  app-network:
    driver: overlay

In this Compose file:

  • image: Specifies the Docker image to use. This should be built and pushed to a registry (e.g., Docker Hub, AWS ECR).
  • ports: Maps host ports to container ports. For a web service, this is typically port 80 or 443. Swarm’s ingress routing mesh will handle distributing traffic.
  • environment: Sets environment variables for the application. Crucially, DB_HOST points to our database service name.
  • deploy: This section is Swarm-specific. replicas: 3 tells Swarm to maintain three running instances of this service. restart_policy ensures containers are restarted if they fail. update_config defines rolling updates.
  • networks: We define an overlay network, which is necessary for multi-host Swarm communication.

Integrating with a Database Service

Microservices often rely on external services like databases. We’ll include a MySQL service in our Swarm deployment.

version: '3.8'

services:
  api:
    # ... (previous api service definition) ...

  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: mydatabase
      MYSQL_USER: user
      MYSQL_PASSWORD: password
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - app-network
    deploy:
      replicas: 1 # Typically, databases are not scaled horizontally in Swarm directly
      restart_policy:
        condition: on-failure

volumes:
  db_data:

networks:
  app-network:
    driver: overlay

Key points for the database service:

  • image: mysql:8.0: Uses an official MySQL image.
  • environment: Configures the MySQL instance. These values must match the environment variables set in the api service.
  • volumes: - db_data:/var/lib/mysql: Persists database data using a Swarm volume. This volume will be managed by Swarm and can be attached to the container regardless of which node it runs on.
  • replicas: 1: For stateful services like databases, horizontal scaling within Swarm is often not straightforward. High availability for databases typically involves replication mechanisms specific to the database (e.g., MySQL replication, Galera Cluster) or using managed database services.

Deploying to Docker Swarm

Once your Dockerfile is built and pushed to a registry, and your docker-compose.yml is ready, you can deploy it to your Swarm cluster.

Building and Pushing the Docker Image

Navigate to your Laravel project’s root directory (where the Dockerfile is) and run:

docker build -t your-dockerhub-username/laravel-api:latest .
docker push your-dockerhub-username/laravel-api:latest

Replace your-dockerhub-username with your actual Docker Hub username or your private registry path.

Deploying the Stack

On your Swarm manager node, deploy the stack using the docker stack deploy command:

docker stack deploy -c docker-compose.yml my-laravel-app

This command tells Swarm to create or update services defined in docker-compose.yml under the stack name my-laravel-app. Swarm will then pull the specified image and start the defined number of replicas on the available worker nodes.

Verifying the Deployment

Check the status of your services:

docker stack services my-laravel-app

You should see your api and database services listed, along with the desired and running replica counts. To see individual tasks (containers):

docker stack ps my-laravel-app

Achieving High Availability and Load Balancing

Docker Swarm’s built-in ingress routing mesh is key to high availability and load balancing. When you publish a port for a service (e.g., port 80 for the API), Swarm configures IPtables rules on *every* node in the cluster. This means you can send traffic to port 80 on *any* node in the Swarm, and Swarm will route it to a healthy container of the `api` service, even if that container is running on a different node.

If a node running an API container goes down, Swarm detects this and automatically reschedules the failed task onto a healthy node. Because we defined replicas: 3, the loss of one instance (or even a node) won’t cause downtime for the API.

External Load Balancer Integration

For production environments, it’s common practice to place an external load balancer (like HAProxy, Nginx, or a cloud provider’s LB) in front of the Swarm cluster. This external LB would distribute traffic across the Swarm nodes on the published port (e.g., port 80). This provides an additional layer of redundancy and allows for more sophisticated traffic management (e.g., SSL termination, health checks).

The external load balancer would target the IP addresses of your Swarm nodes on port 80. Swarm’s internal routing mesh then takes over to direct traffic to the appropriate container.

Advanced Considerations

Configuration Management

Storing sensitive information like database passwords directly in docker-compose.yml is not recommended for production. Docker Secrets are the preferred method for managing sensitive data in Swarm. You can define secrets and mount them as files into your containers.

version: '3.8'

services:
  api:
    # ...
    secrets:
      - db_password
    # ...

secrets:
  db_password:
    file: ./db_password.txt # Or use external secrets

The content of db_password.txt would be your database password. This file is then mounted into the container, typically at /run/secrets/db_password. Your Laravel application would then read this file to get the password.

Health Checks

Swarm’s default health checks are basic. For more robust health checking, you can define custom health checks within your Dockerfile or use a dedicated health check endpoint in your Laravel application. Swarm can be configured to periodically check the health of your containers and automatically remove unhealthy ones from the service pool.

services:
  api:
    # ...
    deploy:
      # ...
      endpoint_mode: dnsrr # Or vip
      update_config:
        # ...
      restart_policy:
        condition: on-failure
      # Add healthcheck to the service definition
      health_check:
        test: ["CMD", "curl", "-f", "http://localhost/health"] # Example health check endpoint
        interval: 30s
        timeout: 10s
        retries: 3
        start_period: 60s

Ensure your Laravel application has a route (e.g., /health) that returns a 200 OK status code when the application is healthy.

Multi-Manager High Availability

For true high availability of the Swarm control plane itself, you need multiple manager nodes. Initialize the first manager as shown previously. Then, on subsequent manager nodes, use the docker swarm join --token manager command (obtained from the initial manager) to join them as managers.

# On the first manager:
docker swarm init --advertise-addr 

# On the second manager:
docker swarm join --token SWMTKN-M --advertise-addr  :2377

# On the third manager:
docker swarm join --token SWMTKN-M --advertise-addr  :2377

With an odd number of managers (typically 3 or 5), Swarm uses a Raft consensus algorithm to ensure that the cluster state is consistent and that the control plane remains available even if one manager node fails.

Zero-Downtime Deployments

Docker Swarm’s rolling update strategy, configured via update_config in the deploy section, is crucial for zero-downtime deployments. By setting parallelism and delay, Swarm gradually replaces old service tasks with new ones. This ensures that there are always healthy instances of your service available to handle incoming requests during an update.

For instance, parallelism: 2 means Swarm will update up to 2 tasks concurrently. delay: 10s means Swarm waits 10 seconds between updating batches of tasks. This allows you to deploy new versions of your Laravel application without interrupting service availability.

Recent Posts

Top Categories

Our Products

Our Services