Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » Migrating Laravel Monoliths to Microservices with Docker & AWS ECS: A Phased Approach

Migrating Laravel Monoliths to Microservices with Docker & AWS ECS: A Phased Approach

Deconstructing the Monolith: Initial Assessment and Service Identification

The first critical step in migrating a Laravel monolith to a microservices architecture is a thorough understanding of its current structure and identifying logical boundaries for new services. This isn’t about arbitrarily splitting code; it’s about domain-driven design principles. We need to identify cohesive units of functionality that can operate independently. Common candidates include:

  • User Authentication & Authorization
  • Product Catalog Management
  • Order Processing & Fulfillment
  • Payment Gateway Integration
  • Notification Services (Email, SMS)
  • Reporting & Analytics

For each identified domain, we’ll perform a deep dive into the existing Laravel codebase. This involves analyzing Eloquent models, controllers, service providers, and any external dependencies. The goal is to isolate the code responsible for a specific domain, minimizing its coupling to other parts of the monolith. Tools like static analysis (e.g., PHPStan, Psalm) can be invaluable here to map dependencies and identify potential refactoring targets.

Containerizing the Monolith: The Foundation with Docker

Before we can break apart the monolith, we need to containerize it. Docker provides the essential isolation and portability required for a microservices environment. We’ll start by creating a robust `Dockerfile` for the existing Laravel application. This `Dockerfile` should be optimized for production, including multi-stage builds to keep the final image lean.

Here’s a sample `Dockerfile` for a typical Laravel application:

# syntax=docker/dockerfile:1

# ---- Base Stage ----
FROM php:8.2-fpm AS base

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    acl \
    vim \
    cron \
    supervisor \
    && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    zip \
    pcntl \
    pdo_mysql \
    bcmath \
    exif \
    gettext \
    intl \
    opcache

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

# Set working directory
WORKDIR /var/www/html

# Copy application files
COPY . .

# Install Composer dependencies
RUN composer install --no-dev --no-autoloader --no-scripts && composer clear-cache
RUN composer install --no-dev --optimize-autoloader --no-scripts

# Copy application configuration
COPY .env.example .env
# You might want to manage .env secrets via environment variables in ECS,
# but for initial containerization, this is a starting point.

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

# Install Node.js and npm (if frontend assets need building)
RUN apt-get update && apt-get install -y nodejs npm \
    && rm -rf /var/lib/apt/lists/*
RUN npm install && npm run build

# Copy supervisor configuration
COPY docker/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf

# Expose port
EXPOSE 9000

# Start supervisor
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"]




The `supervisord.conf` would typically manage PHP-FPM and potentially a queue worker. A simplified example:





[supervisord]
nodaemon=true
user=root

[program:php-fpm]
command=/usr/local/sbin/php-fpm --nodaemonize
autostart=true
autorestart=true
user=www-data
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:queue-worker]
command=php artisan queue:work --tries=3 --timeout=60 --sleep=5 --daemon
autostart=true
autorestart=true
user=www-data
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0






Once the `Dockerfile` is in place, build the image and test it locally using Docker Compose. This ensures the monolith runs correctly in a containerized environment before we start splitting it.





Phased Migration Strategy: Extracting Services Incrementally





The key to a successful migration is a phased approach. We don't rewrite everything at once. Instead, we extract one service at a time, deploy it independently, and then refactor the monolith to call this new service.





Phase 1: Extracting the User Service





Let's take the User Authentication and Authorization service as our first extraction. This service will be responsible for user registration, login, profile management, and potentially role/permission management.





1. Create a New Laravel Project for the User Service:





composer create-project --prefer-dist laravel/laravel user-service
cd user-service






2. Isolate User-Related Code: Copy relevant models (e.g., `User`), controllers, middleware, and any supporting classes from the monolith to the new `user-service` project. Remove code not directly related to user management.





3. Database Schema: The `user-service` will need its own database or a dedicated schema within a shared database. For simplicity in this example, let's assume a separate database. Migrate the `users` table schema to the new service.





4. API Endpoints: Define API routes within `user-service` for operations like user creation, retrieval, authentication (e.g., issuing JWTs or session tokens), and profile updates. Use Laravel's API resources for consistent data formatting.





// user-service/routes/api.php
use App\Http\Controllers\AuthController;
use App\Http\Controllers\UserController;

Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login']);

Route::middleware('auth:api')->group(function () {
    Route::get('/user', [UserController::class, 'show']);
    Route::put('/user', [UserController::class, 'update']);
    // ... other user-related routes
});






5. Containerize the User Service: Create a `Dockerfile` for `user-service` similar to the monolith's, but tailored for its specific needs. This will likely be a simpler `Dockerfile` without frontend build steps.





Orchestration with AWS ECS and Docker Compose





AWS Elastic Container Service (ECS) is a powerful, scalable container orchestration service. We'll use it to deploy and manage our microservices. For local development and testing, Docker Compose is indispensable.





Local Development with Docker Compose





Create a `docker-compose.yml` file that defines your monolith (as a service) and the new `user-service`, along with any necessary dependencies like databases and caches.





version: '3.8'

services:
  # The original monolith, now running as a container
  monolith:
    build:
      context: ./monolith # Path to your monolith's Dockerfile
      dockerfile: Dockerfile
    ports:
      - "8000:80" # Expose monolith's web server
    volumes:
      - ./monolith:/var/www/html
    environment:
      DB_HOST: db
      REDIS_HOST: redis
      USER_SERVICE_URL: http://user-service:9000 # Point to the user service

  # The new user service
  user-service:
    build:
      context: ./user-service # Path to user-service's Dockerfile
      dockerfile: Dockerfile
    ports:
      - "9001:9000" # Expose user-service's PHP-FPM
    volumes:
      - ./user-service:/var/www/html
    environment:
      DB_HOST: db
      REDIS_HOST: redis
      APP_URL: http://localhost:9001 # For user-service's internal use

  # Database for user service
  db:
    image: mysql:8.0
    ports:
      - "3307:3306"
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: user_service_db
    volumes:
      - db_data:/var/lib/mysql

  # Cache service
  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

volumes:
  db_data:






With this `docker-compose.yml`, you can start your entire environment locally with `docker-compose up -d`. The monolith will now need to be refactored to communicate with the `user-service` API instead of accessing user data directly.





Deploying to AWS ECS





For ECS, we'll define Task Definitions and Services. A Task Definition specifies the Docker image(s) to run, CPU/memory requirements, and environment variables. A Service maintains a desired count of tasks and handles scaling and load balancing.





1. Build and Push Docker Images: Build your monolith and `user-service` Docker images, tag them with your ECR repository URI, and push them.





# For monolith
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin YOUR_AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com
docker build -t YOUR_AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/monolith:latest ./monolith
docker push YOUR_AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/monolith:latest

# For user-service
docker build -t YOUR_AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/user-service:latest ./user-service
docker push YOUR_AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/user-service:latest






2. Create ECS Task Definitions: Define Task Definitions for both the monolith and the `user-service` in the AWS console or via the AWS CLI/CDK/Terraform. Key elements include:





  • Image URI: The ECR image URI.
  • Port Mappings: Expose the container ports (e.g., 9000 for PHP-FPM, 80 for web server).
  • Environment Variables: Database credentials, service discovery endpoints (e.g., `USER_SERVICE_URL`), AWS credentials, etc. Use AWS Secrets Manager for sensitive data.
  • CPU/Memory: Allocate appropriate resources.





3. Set up Load Balancers and Target Groups: Use an Application Load Balancer (ALB) to route traffic. Create Target Groups for your monolith's web server port and potentially for the `user-service` if it needs direct external access (though often it's accessed internally via service discovery or ALB rules).





4. Create ECS Services: Define ECS Services for both the monolith and `user-service`. Each service will:





  • Reference its Task Definition.
  • Associate with the ALB's Target Group(s).
  • Specify the desired number of tasks (for scaling).
  • Configure networking (VPC, subnets, security groups).





5. Refactor Monolith for Service Communication: Update the monolith's code to use an HTTP client (like Guzzle) to call the `user-service` API. Ensure proper error handling and retries.





// monolith/app/Http/Controllers/ProfileController.php
use Illuminate\Support\Facades\Http;

public function show()
{
    $userServiceUrl = config('services.user_service.url'); // e.g., http://user-service:9000
    $userId = auth()->id(); // Assuming auth is still handled by monolith for now, or token passed

    try {
        $response = Http::withToken(session('api_token'))->get("{$userServiceUrl}/api/user");
        $userData = $response->json();
        return view('profile.show', compact('userData'));
    } catch (\Exception $e) {
        // Handle error: user service unavailable, invalid token, etc.
        return back()->withErrors('Could not load user profile.');
    }
}






The `config/services.php` in the monolith would be updated:





// monolith/config/services.php
'user_service' => [
    'url' => env('USER_SERVICE_URL', 'http://user-service:9000'),
],






And the `USER_SERVICE_URL` environment variable would be set in the monolith's ECS Task Definition or via a `.env` file if using Fargate with secrets.





Subsequent Phases and Advanced Considerations





Repeat the extraction process for other identified domains (e.g., Products, Orders). Each new service will follow a similar pattern: isolate code, create a new Laravel project, containerize, deploy to ECS, and refactor the monolith to consume its API.





Database Strategy





As services become independent, their databases should ideally become independent too. This avoids tight coupling. Strategies include:





  • Separate Databases: Each service has its own RDS instance or Aurora cluster.
  • Shared Database, Separate Schemas: A single RDS instance, but each service uses its own schema. Simpler to manage initially but less isolated.
  • Database per Service (Polyglot Persistence): Different services might use different database technologies (e.g., PostgreSQL for relational data, DynamoDB for key-value, Elasticsearch for search).





Data consistency across services is a major challenge. Consider patterns like the Saga pattern for distributed transactions, or eventual consistency using event sourcing and message queues (e.g., SQS, Kafka).





Inter-Service Communication





Beyond simple REST APIs, consider:





  • Asynchronous Communication: Using message queues (SQS, RabbitMQ, Kafka) for decoupling. A service publishes an event (e.g., `OrderPlaced`), and other services subscribe to it.
  • gRPC: For high-performance, low-latency communication between services, especially if performance is critical.
  • Service Discovery: ECS integrates with AWS Cloud Map for service discovery, allowing services to find each other by name without hardcoding IPs or hostnames.





CI/CD Pipeline





A robust CI/CD pipeline is essential. For each microservice, you'll want a pipeline that:





  • Triggers on code commits.
  • Runs linters and static analysis.
  • Runs unit and integration tests.
  • Builds the Docker image.
  • Pushes the image to ECR.
  • Updates the ECS Task Definition and Service (e.g., using AWS CodePipeline, Jenkins, GitLab CI, GitHub Actions).





The monolith's pipeline will also need to be maintained, potentially with modifications to integrate with new services or to eventually shrink as functionality is extracted.





Conclusion





Migrating a Laravel monolith to microservices is a significant undertaking. By adopting a phased approach, leveraging Docker for containerization, and utilizing AWS ECS for orchestration, you can manage complexity and reduce risk. Start small, extract one cohesive domain at a time, and iteratively build your microservices architecture. Remember that this is an architectural evolution, not a rewrite, and requires careful planning, robust testing, and a strong understanding of distributed systems principles.

Recent Posts

Top Categories

Our Products

Our Services