How I Solved Architecture Mismatches When Containerizing a Flutter Web App on an M1 Mac and Deploying to AWS ECS

Recently, I worked on a project to containerize a Flutter web app and deploy it using AWS ECS on an EC2 instance. If you’re using Docker on an M1 Mac and trying to deploy to AWS, you might encounter architecture compatibility issues, as I did. Here’s how I identified and solved the problem by rethinking my Dockerfile setup and addressing AWS constraints.

The Problem: Platform Mismatch

When I initially tried to build a Flutter web application using Docker, I encountered the following error:

InvalidBaseImagePlatform: Base image cirrusci/flutter:latest was pulled with platform "linux/amd64", expected "linux/arm64" for current build

This error occurs because the Docker base image I was using (cirrusci/flutter:latest) was designed for amd64architecture, while my M1 Mac uses an arm64 architecture. The mismatch caused Flutter build commands to fail.

Initial Thoughts

At first, I considered using Docker’s --platform flag to emulate amd64. While this can work, it introduces performance overhead and potential compatibility issues. I wanted a solution that would:

• Build natively for my M1 Mac’s ARM architecture.
• Avoid relying on architecture emulation.
• Use simple, flexible, and efficient Docker configurations.

The Solution: A Two-Stage Dockerfile

The breakthrough came when I came across an article on Medium (unfortunately, I can’t find it to reference) that explained how to separate the build process from the runtime environment. This is what my updated Dockerfile looks like:

Stage 1: The Builder

# Stage 1 - Builder
FROM ubuntu:20.04 AS builder

# Ensure you're running as root
USER root

# Install dependencies
RUN apt-get update && apt-get install -y \
    bash \
    curl \
    file \
    git \
    unzip \
    xz-utils \
    zip \
    libglu1-mesa \
    && apt-get clean

# Clone the Flutter repo
RUN git clone https://github.com/flutter/flutter.git /usr/local/flutter

# Set Flutter path
ENV PATH="/usr/local/flutter/bin:/usr/local/flutter/bin/cache/dart-sdk/bin:${PATH}"

# Change stable channel
RUN flutter channel stable

# Enable web capabilities
RUN flutter config --enable-web
RUN flutter upgrade
RUN flutter pub global activate webdev

# Verify Flutter installation
RUN flutter doctor -v

# Copy application code into container and build
WORKDIR /app
COPY . /app
RUN flutter pub get
RUN flutter build web --no-tree-shake-icons  # Disable icon tree-shaking

Stage 2: The Runtime

This stage uses a lightweight NGINX server to serve the prebuilt Flutter web files.

# Stage 2 - Create the run-time image
FROM nginx:stable-alpine AS runner

# Copy custom NGINX configuration and build output from builder
COPY default.conf /etc/nginx/conf.d
COPY --from=builder /app/build/web /usr/share/nginx/html

# Set default command to start nginx
CMD ["nginx", "-g", "daemon off;"]

Custom NGINX Configuration

I added a simple NGINX configuration (default.conf) to handle serving the web app:

server {
    listen       80;
    listen  [::]:80;
    server_name  localhost;

    root /usr/share/nginx/html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

Why This Works

1. ARM-Compatible Base Images

Both ubuntu:20.04 (for building) and nginx:stable-alpine (for runtime) have ARM-compatible versions. Docker automatically pulls the appropriate image for my M1 Mac.

2. Separation of Build and Runtime Stages

• The builder stage installs Flutter and runs all commands required to build the app. This ensures the Flutter setup is tailored to the ARM architecture on my Mac.
• The runtime stage is lightweight and only serves the already-built web files using NGINX. It doesn’t need Flutter, so there are no compatibility concerns.

3. No Architecture Emulation

By avoiding prebuilt images like cirrusci/flutter (which are amd64-specific), I sidestep the need for architecture emulation, improving build speed and compatibility.

4. Efficient and Portable

This setup ensures the build process is efficient, while the runtime image is portable and optimized for deployment.

Building and Running the Docker Image

Here’s how to build and run the Docker image:

Build the Image

docker build -t flutter-web-app .

Run the Container

docker run -p 80:80 flutter-web-app

Now, you can access your Flutter web app at [http://localhost:80.](http://localhost:8080.)

Moving to AWS: A New Challenge

After successfully containerizing the Flutter app, I wanted to deploy it to AWS. I decided to push the Docker image to AWS Elastic Container Registry (ECR) and use it with AWS Elastic Container Service (ECS) running on an EC2 instance. However, I encountered a new issue: the container wouldn’t run.

The issue arose because I was using AWS’s free tier, and the t2.micro instance type I chose for the ECS cluster only supports the amd64 (also known as x86_64) architecture, not arm64. To resolve this, I rebuilt the Docker image specifically for the amd64 architecture to ensure compatibility with the t2.micro instance.

docker buildx build --platform linux/amd64 -t e_shop_opti_image .

After rebuilding the image, I pushed it to AWS ECR, created an ECS cluster with an EC2 instance compatible with amd64, and adjusted the security group and port settings to make the app accessible. Finally, it worked!

Lessons Learned

1. Choose Compatible Base Images: Always ensure your base images and deployment environments support your desired architecture.
2. Rebuild for Specific Architectures: When working across platforms, you might need to rebuild your Docker images for compatibility.
3. Plan Deployment Environments: Understand the limitations of your cloud resources (e.g., AWS free tier).