🐳 Python FastAPIアプリケーションをDockerでコンテナ化し、ARM vs x86 アrchitecture 問題を解決する

== タイトルの詳細 == Dockerを使ってコンテナ化したアプリケーションは、デプロイの予測可能性と一貫性を持つようにします。通常、何かが自分のマシンで動作すれば、どこも同じ結果になります。 しかし、実世界環境では、徐々に小さな問題や違いを見つけ出すことがあります。 特に異なるCPUアーキテクチャを持つx86 (AMD64)マシンとARM64マシン上でのアプリケーションを作成する際にです。== レコードの内容 == 今私はPython FastAPIの小さなスクリプトをコンテナ化して、それを見ていました。 それが私のUbuntuサーバーでどのように動作しても問題ないように見えましたが、別のマシンで違う様子でした。 調査を続けた結果、システム間のアーキテクチャ差異が原因でした。 この記事では全体的なプロセスについて詳しく説明します: FastAPIアプリケーションをDockerでコンテナ化するに至る Docker Composeを使用してアプリケーションを実行するに至る ARM vs x86 のアーキテクチャ差異の理解 Dockerデーモン問題のトラブルシュ setPosition1 多機能なイメージを構築する Python、FastAPI、Docker、またはクラウドデプロイメントに取り組んでいる場合にも役立ちます。 == 実際のプロジェクトの構造 == ここでは非常に基本的なサンプルを使用します。それは「タスクAPIサービス」と呼ばれる小さなAPIサービスです。 === プロジェクトの構造 === task-api-service より Python FastAPIアプリケーションがポート8080を使用してREST APIを公開します。 == ステップ1 — Dockerfile を作成する == 最初のステップとして、Dockerファイルを作成してアプリケーションをコンテナ化するようにします。 これには、一般的に使用されるPython slimイメージが含まれます。そのイメージは軽量な基底オーバー環境を持っています。 ** 適用プロジェクトの手順 === FROM python:3.10-slim * 環境 variableを設定します ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1 * ディレクトリのウェアリング WORKDIR /app * apt-getアップデートとインストール（必要に応じて） RUN apt-get update && apt-get install -y libgl1 libglib2.0-0 build-essential && rm -rf /var/lib/apt/lists/ * COPY requirements.txt . * 結果をPipインストールする RUN pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt * コピーを実行 COPY . . * ポート8080を開く EXPOSE 8080 * CMD[ "uvicorn","main:app", "--host","0.0.0.0... *これらの最適化の詳細 === 現在のファイル内に何がありますか？1️⃣ Pythonのキャッシュファイルを防ぐ。PYTHONDONTWRITEBYTECODE=1 ・ビルドとインストールの改善により、このコンテナはプロダクション環境でも使用できます。 1️⃣ プログラムのキャッシュファイルを防ぐことにより、.pyc の拡張子を .py に変更し、Pythonの拡張サーケットを避けることができることになります、これにより、Pythonコードがコンテナにコピーされたときからその結果が反映されることを避けられます。 2️⃣ ログを優先することにより、このコンテナはすぐに Docker のログで見ることができるようになりました。 3️⃣ このリムーブ コマンドにより、最終的なイメージサイズが小さくなりました、これにより、Pythonのパッケージのカクレースセットは消えることができます。 == Step 2: イメージを構築する === Docker ファイルが準備できたら、イメージを作成します。 (docker build を実行します) docker build -t task-api-service . == コンテナの実行 == そしてそれをどのように動作させるかを見ることができました。 docker run 〜 ホストのポートをコンテナにマップできます。 docker run -p :8080 task-api-service 以上、アプリケーションは以下の URL を通過するように指示されます: HTTP /localhost:8088 == Docker Composeを使用する === 複数のアプリケーションが存在していると手動で管理を停止し、 Docker Compose の便利さを利用できます。Docker Compose が実際には何であるかをご理解いただければと思います。 ファイルを作成します：docker-compose.yml version: "3.9" services: fastapi-app: container_name: fastapi-app build: (コンテナ名を指定する) context: dockerfile: service ports: 端口をマップするportsは、host と containerのいずれかに任意のポート数のものを持つことができます。 volumesと外部ディレクトリとの組み合わせがサポートされています。 テキストやディレクトリの中身だけでなく、そのドライブまでコピーできます。 gitなどの外から参照されるものを含めてください。 == キャメルとターゲットの差異（ARM vs x86） === 私の Ubuntu 動作がすべてうまく行ったときでした。システム構造を確認するには以下のコマンドを実行します、uname -m その結果はこのようになっていた: x86_64 (これはAMD64アーキテクチャです) ただし、最近のシステムでは ARM アーキテクチャであることが多くあります。ARM64と呼ばれます。 それにもかかわらず、次のデバイスはそのアーキテクチャを使用する可能性があります: Apple（特にiPadPro）。 これにより、ARMのデーモン問題が発生したのでそれを説明します。 まず、Docker コンテナには実行時パスやシステムサードパーティコード(ライブラリ)が存在しません。しかし、「volumes」オプションを設定すると、これによりドメインが問題を引き起こすことができます。 volumesの設定: 〜docker-compose.yml 「.:/app」 このドライブと外部ディレクトリに相対的なパスとして参照されます。 これが、コードの変更が常に反映されるためコードベース全体に影響を与えます。そしてプロジェクトの再構築やオートリロードなどが行われます。そのため、一般的に多くの人に対して必要だとされています。 ⚠️ Dockerでクラスタリングをテストする場合、Docker インデックスが問題を引き起こす可能性があります。この問題に対する最も一般的な解決策はDocker Composeを介した別のネットワークを作成することによって生まれます。これにより、「Docker」と「Network」というタグを持つ新しいネットワーク名で実現できます。 docker-compose -f docker-compose.yml --network new-net up 他のアプリケーションがクラスタリングするような、新しい networkの名前を使用します: (この新しく設定された network) 'new-net' docker compose命令を実行すると、既存のイメージまたはコンテナで構成されているネットワークに複製されるようになります new-net。 ただし、それ自身の networkを用いて別のネットワークを構築することができます。 新しい networkを定義し、それを「networks」キーの新たなオプションとして追加すると、特定のコマンドラインオプションがこのネットワーキングを通じて適用されます。また、「docker」と「Network」タグが付与されます。 これらのネットワークに新しいコンテナを作成することができます。 そのため、Docker Composeを使ってクラスタリングとネットワークを管理することが一般的であるため、「networks」キーのオプションを使用し続けることは重要です。 また、この問題は Docker コマンドラインツールを含めることができます。 これは一貫性、信頼性そして問題解決法に非常に役立つです。 イメージとネットワークに対して異ならないようにします。 これらの「タグ」はコンテナ名のリストによって保持されます。 これらは Docker の複数のクラスタリングの一部になり、異なるコンポーネントから各アプリケーションが利用可能になります。

When working with containerized applications, Docker usually makes deployments predictable and consistent. Once everything is packaged inside a container, the expectation is simple: “If it works on my machine, it should work everywhere.” However, real-world environments sometimes introduce subtle issues — especially when applications are built on machines with different CPU architectures, such as x86 (AMD64) and ARM64. Recently, I was containerizing a small Python FastAPI application, and I noticed something interesting. The Docker image worked perfectly on my Ubuntu server but behaved differently on another machine. After some investigation, the root cause turned out to be architecture differences between systems. In this article, I'll walk through the entire process: Containerizing a FastAPI application with Docker Running the application using Docker Compose Understanding ARM vs x86 architecture differences Troubleshooting Docker daemon issues Building multi-architecture images If you work with Python, FastAPI, Docker, or cloud deployments, this guide will help you avoid some common pitfalls. 📁 Project Structure For this example, we'll use a simple API service called task-api-service. The project structure looks like this: task-api-service The FastAPI application exposes a REST API running on port 8080. 🐍 Step 1 — Writing the Dockerfile The first step is creating a Dockerfile to containerize the application. We start with the official Python slim image, which provides a lightweight base environment. FROM python:3.10-slim ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1 WORKDIR /app RUN apt-get update && apt-get install -y \ libgl1 \ libglib2.0-0 \ build-essential \ && rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --upgrade pip \ && pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8080 CMD ["uvicorn","main:app","--host","0.0.0.0","--port","8080"] Why these optimizations? There are a few small improvements here that make the container more production-friendly. 1️⃣ Prevent Python cache files PYTHONDONTWRITEBYTECODE=1 This prevents .pyc files from being created inside the container. 2️⃣ Better logging PYTHONUNBUFFERED=1 This ensures logs are immediately visible in Docker logs. 3️⃣ Removing package cache rm -rf /var/lib/apt/lists/* This reduces the final image size. 🏗 Step 2 — Building the Docker Image Once the Dockerfile is ready, we can build the image. docker build -t task-api-service . After building, verify the image: docker images You should see the new image listed. 🚀 Step 3 — Running the Container Now we can run the container. docker run -p 8088:8080 task-api-service The application will now be accessible at: http://localhost:8088 Docker maps: Host Port 8088 → Container Port 8080 ⚙️ Step 4 — Using Docker Compose Managing containers manually becomes inconvenient as applications grow. This is where Docker Compose becomes useful. Create a file called docker-compose.yml. version: "3.9" services: fastapi-app: container_name: fastapi-app build: context: . dockerfile: Dockerfile ports: - "8088:8080" volumes: - .:/app restart: unless-stopped 📂 Why Use Volumes? volumes: - .:/app This mounts the local project directory into the container. Benefits include: Instant reflection of code changes Faster development workflow No need to rebuild images repeatedly If you run Uvicorn with the --reload flag, the server automatically restarts when files change. ▶️ Running with Docker Compose Start the application: docker compose up --build Run it in the background: docker compose up -d Stop the containers: docker compose down ⚠️ The Architecture Problem (ARM vs x86) Everything worked perfectly on my Ubuntu machine. To check the system architecture, I ran: uname -m Output: x86_64 This means the system uses AMD64 architecture. However, many modern systems now use ARM architecture, including: Apple Silicon Macs AWS Graviton instances Raspberry Pi servers Running the same command on those systems usually returns: arm64 This difference can cause compatibility issues when Docker images are built on one architecture and run on another. 🔧 Forcing a Specific Docker Platform Docker allows specifying the target architecture during builds. For example: docker build --platform linux/arm64 -t task-api-service . This forces Docker to build an ARM-compatible image. You can also define the platform inside Docker Compose. services: fastapi-app: build: context: . platform: linux/arm64 ports: - "8088:8080" 🛠 Troubleshooting Docker Daemon Issues During testing, I encountered an error like this: Cannot connect to the Docker daemon at unix:///var/run/docker.sock This usually means the Docker daemon is not running. To verify Docker status: sudo systemctl status docker If the service is inactive, restart it: sudo systemctl restart docker Then confirm Docker is working: docker ps 🔐 Fixing Docker Permission Issues Another common issue occurs when Docker commands require sudo. This happens because the user is not part of the Docker group. To fix it: sudo usermod -aG docker $USER Then reload the shell: newgrp docker Now Docker commands can run without sudo. 🌍 Best Practice: Multi-Architecture Docker Images Instead of building separate images for ARM and x86 systems, Docker allows multi-architecture builds. Using Docker Buildx: docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myrepo/task-api-service:latest \ --push . This creates a single image compatible with multiple architectures. Official Docker images such as: Python Node.js Nginx all use this approach. 🧠 Final Thoughts Docker makes it easy to package and deploy applications consistently, but architecture differences can sometimes introduce unexpected issues. A few key lessons from this experience: Always check system architecture using uname -m Use Docker Compose for easier container management Ensure the Docker daemon is running before troubleshooting builds Consider multi-architecture images for production deployments By understanding these concepts, you can ensure your containerized applications run smoothly across different environments, cloud platforms, and development machines.