松本侑真 — #docker

Uvicornを用いたFlaskの本番起動について

Sat, 14 Feb 2026 13:04:43 GMT

想定する基本的なディレクトリ構成

flaskアプリのディレクトリ構成

.
├─ templates
│   ├─ index.html
│   └─ result.html
├─ Dockerfile
├─ app.py      # Flaskアプリケーションのエントリーポイント
├─ asgi.py     # ASGIアプリ化を行うためのファイル
├─ compose.yml
├─ pyproject.toml
└─ uv.lock

app.py にはFlaskアプリケーションのコードが記述されています。これらは uv で管理されているプロジェクトとしています。

app.py

from flask import Flask, render_template

app = Flask(__name__)

def solve_problem():
    results = ...
    return results

@app.route('/', methods=['GET'])
def index():
    return render_template('index.html')

@app.route('/solve', methods=['POST'])
def solve():
    results = solve_problem()
    return render_template('result.html', results=results)

if __name__ == '__main__':
    app.run(debug=True, port=5000, threaded=True)

アプリ開発時のFlaskの起動方法

uv run コマンドで開発サーバーを起動します。

uv run flask run

このコマンドを実行すると、Flaskに内蔵されている簡易サーバー (Werkzeug) が起動し、http://localhost:5000 でアプリケーションにアクセスできるようになります。

しかしWerkzeugは開発用のサーバーであり、本番環境での使用は推奨されていません。

セキュリティ的に脆弱である
パフォーマンスが低い
安定性や運用機能がない

ことが理由です。

本番環境でのFlask起動方法

本番環境では、Gunicorn や uWSGI といったWSGIサーバー、あるいは Uvicorn といったASGIサーバーを使用してFlaskアプリケーションを起動します。これらはPython向けの本番用サーバーモジュールで、本番運用を想定したセキュリティやパフォーマンスを提供します。

Uvicornを用いたFlaskの起動

Important

結論：Flask をASGIアプリ化すれば Uvicorn で起動できる。

asgi.py（ASGI変換コード）

import os
from asgiref.wsgi import WsgiToAsgi
from app import app as flask_app # Flask APPのインポート

app = WsgiToAsgi(flask_app)

Uvicornでの起動コマンド

uv run uvicorn asgi:app \
    --host 0.0.0.0 \
    --port 8000 \
    --workers 1

Traefikをリバースプロキシとして利用する

既にTraefikをコンテナで起動して、app-gallery ネットワークに接続している前提とします。

Flaskアプリケーションを起動するための compose.yml には、Traefikのルーティング設定を行うためのラベルを追加します。

compose.yml（Traefikを用いたパスルーティング）

services:
  gallery:
    build:
      context: .
      dockerfile: Dockerfile
    networks: [app-gallery]
    env_file:
      - .env
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${APP_ID}.rule=Host(`${APP_HOST}`) && PathPrefix(`/${APP_ID}`)"
      - "traefik.http.routers.${APP_ID}.entrypoints=web" # 80番ポートから来た通信のみを処理する
      - "traefik.http.services.${APP_ID}.loadbalancer.server.port=${APP_PORT}"
      # - "traefik.http.middlewares.${APP_ID}-strip.stripprefix.prefixes=/${APP_ID}"
      # - "traefik.http.routers.${APP_ID}.middlewares=${APP_ID}-strip"

networks:
  app-gallery:
    external: true

以下でこれらの設定内容を説明します。

ルーティング条件

Hostが ${APP_HOST}
かつ、パスが /${APP_ID} で始まる

ルクエストだけをこのサービスに流す

"traefik.http.routers.${APP_ID}.rule=Host(`${APP_HOST}`) && PathPrefix(`/${APP_ID}`)"

転送先ポート

Flaskアプリの起動コマンドで指定したポートをTraefikに伝える

"traefik.http.services.${APP_ID}.loadbalancer.server.port=${APP_PORT}"

Traefikのルーティングに対応させたミドルウェア設定

Traefikを使うことで、host/${APP_ID} というパスでFlaskアプリケーションにアクセスできるようになります。

一方で、Flaskアプリケーション側ではリクエストのパスが /${APP_ID} から始まることを想定していないため、ルーティングエラーが発生してしまいます。

これらの問題を解決するために、Flaskアプリケーション側でリクエストのパスから /${APP_ID} を取り除くミドルウェアを実装します。

app.py（ミドルウェア部分を抜粋）

app = Flask(__name__)

class PrefixMiddleware:
    def __init__(self, app, prefix=''):
        self.app = app
        self.prefix = prefix.rstrip('/')

    def __call__(self, environ, start_response):
        if self.prefix:
            environ['SCRIPT_NAME'] = self.prefix
            path = environ.get('PATH_INFO', '')
            if path.startswith(self.prefix):
                environ['PATH_INFO'] = path[len(self.prefix):] or '/'
        return self.app(environ, start_response)

APP_ID = os.getenv('APP_ID', '').strip()
if APP_ID:
    app.wsgi_app = PrefixMiddleware(app.wsgi_app, prefix='/' + APP_ID)

PrefixMiddleware でやっていること

Important

WSGIの　environ は「リクエスト情報」ですが、ここで2つのキーを調整しています。

SCRIPT_NAME : アプリケーションのルートパスを指定するためのキー
PATH_INFO : ルーティングの対象となるパスを指定する

PATH_INFO から prefix: /${APP_ID} を剥がす

例：Traefikから来るのが PATH_INFO='/APP_ID/some/path'であれば、middlewareで PATH_INFO='/some/path' に変換する。

これにより、Flaskアプリ上で

app.py

@app.route('/some/path')
def some_path():
    ...

と定義したままであっても、Traefik経由で host/APP_ID/some/path にアクセスしたときに正しくルーティングされるようになります。

SCRIPT_NAME に prefix: /${APP_ID} を設定する

SCRIPT_NAME は、FlaskアプリケーションがURLを生成する際に使用する、アプリケーションのルートパスを指定するためのキーです。

例えば、Flaskアプリケーション内で

app.py

@app.route('/some/path')
def some_path():
    return url_for('some_path')

と定義している場合、url_for('some_path') は '/APP_ID/some/path' を返すようになります。

特にHTMLテンプレート内で url_for を使用してパスを生成して、publicなファイルを参照する場合、この設定がないと、生成されるURLが '/static/somefile' のようになってしまい、Traefik経由でアクセスしたときに正しくファイルが参照できなくなります。

パスの処理はTraefikとFlaskのどちらで行うべき？

Traefikの StripPrefix ミドルウェアを使用して、Traefik側でパスの処理を行う方法もあります。

- "traefik.http.middlewares.${APP_ID}-strip.stripprefix.prefixes=/${APP_ID}"
- "traefik.http.routers.${APP_ID}.middlewares=${APP_ID}-strip"

compose.yaml でコメントアウトしたこれら2行を有効化すると、アプリに届く次点で PATH_INFO から /${APP_ID} が剥がされた状態になります。

一方で、 SCRIPT_NAME は基本的に何もしない限り空文字列のままになるので、PublicファイルへのURL生成（url_for）に問題が発生します。

これを回避するためには、Traefikのmiddleware部分で

# middleware 1: パスから prefix を剥がす
- "traefik.http.middlewares.${APP_ID}-strip.stripprefix.prefixes=/${APP_ID}"

# middleware 2: X-Forwarded-Prefix をつける（リクエストにヘッダー追加）
- "traefik.http.middlewares.${APP_ID}-xfp.headers.customrequestheaders.X-Forwarded-Prefix=/${APP_ID}"

# ルーターに middleware を追加する
- "traefik.http.routers.${APP_ID}.middlewares=${APP_ID}-strip,${APP_ID}-xfp"

という設定を行います。 X-Forwarded-Prefix: /${APP_ID} というヘッダーがリクエストに追加され、これをFlaskアプリで読み込んで SCRIPT_NAME に設定することが可能となります。

この方針であれば、Flaskアプリにおいては、${APP_ID} などの環境変数を意識せずに、通常のルーティング定義やURL生成が可能になります。

ただし、HTTPリクエストのヘッダーを意識しないといけないのが面倒で、Traefik経由でのリクエストか、そうでないのかの区別がつきにくく、ローカルでの開発やテストがやりにくくなる可能性もあります。

前者のFlask側でパスの処理を全て行う方針であれば、${APP_ID} が空かどうかの条件分岐を入れるだけで、ローカル環境と本番環境を同じコードベースで運用できるというメリットもあります。

また、Flaskでのmiddlewareは結局必要となるので、どちらでパスの処理を行うかは好みの問題かなと思います。

（余談）WSGIとASGIの違い

種類	特徴	得意なこと
WSGI	同期処理に特化したサーバー	CPU中心の同期処理。シンプルな構成が可能。
ASGI	同期・非同期両方に対応したサーバー	APIサーバーやWebSocket用途。長時間接続やリアルタイム通信が可能。

WSGI の基本思想は、同期モデル (blocking) に基づく処理を行うことです。 1つのリクエストが1スレッド or プロセスで処理され、リクエストの処理が完了するまで次のリクエストは待機します。

WSGIのリクエスト処理モデル

Request
   ↓
Worker（1つのリクエストがブロックする）
   ↓
Response

一方、ASGI は非同期モデル (non-blocking) に基づく処理を行うことができます。

ASGIのリクエスト処理モデル

Request
   ↓
Event Loop
   ↓
I/O待ち中に他リクエスト処理
   ↓
Response

複数のリクエストを同時に処理できるため、APIサーバーやWebSocketなどのリアルタイム通信に適しています。

Platform Engineerに関して

Sat, 31 Jan 2026 22:50:42 GMT

要約

Platform Engineeringは、DevOpsの普及が生んだ認知負荷の問題への回答として登場した
自分の志向（責任分離をはっきりとしたアーキテクチャ、ミスを犯さない構造の事前設計、何しても良い最強の基盤を作りたい）はこの思想と重なる部分が大きい

Platform Engineeringとは何か

2009年頃から DevOps という考え方が広まりました。「You build it, you run it（作ったチームが動かせ）」という原則で、開発と運用の壁をなくすことでデプロイ頻度が上がり、障害対応も速くなりました。

「コード書きました、あとはよろしく」では優れたソフトウェアは生まれない　コンテナのスペシャリストが語る、運用性を損なう8つの実装例 | ログミーBusiness

You build it, you run it原トリ氏：（スライドの「You build it, you run it」を指して）この言葉、聞いたこと、見たことがある方がいるかもしれません。これは、2006年にACM（Associatio...

logmi.jp

DevOps の考えは、「運用性に優れたソフトウェアは重要である」という思想に基づいます。上記のサイトにおいて、運用性を損なう実装の例として

スケールアウトできない、しにくいアプリ実装
依存パッケージ解決を自動化出来ない
安全に停止できない
起動処理が長い
ビルド/パッケージング前に手作業が必要
設定値を実行時に外部から注入できない
ログをファイルにしか出力できない
Read レプリカを使えない

といったものが挙げられています。

これらの実装を避けるため、DevOps の原則を全チームに適用し続けた結果、別の問題が出てきました。各チームが CI/CD を個別に構築し、Dockerfile を管理し、Kubernetes のマニフェストを書く。チームごとにやり方が違う。再利用できない。新しいメンバーは膨大な社内ドキュメントを読まないと最初のデプロイができない、という状況です。

このような状況をソフトウェアエンジニアリングの世界では、「偶有的複雑さ（Accidental Complexity）」という言葉で表現することがあるようです。本質的に難しいわけではないのに、構造の問題で複雑になってしまっている。開発者がインフラ・セキュリティ・監視・デプロイを全て理解しながら機能開発もこなすのは、認知リソース的に無理があります。

Platform Engineering は、この問題への回答として生まれた考え方であり、その中心にある概念が Internal Developer Platform（IDP）です。

IDP とは、開発者が自分のアプリをデプロイ・運用するために使う、社内製の開発者向けプラットフォームのことで、GitHub や Vercel のような体験を社内で提供するものだと考えるとわかりやすいかもしれません。

IDP を設計するとき、「どこまで抽象化するか」が最も難しい問いになります。抽象化しすぎると柔軟性が失われる（Golden Cage と呼ばれます）。抽象化しなさすぎると認知負荷は減らない。このバランスを取るために生まれた概念が Golden Path です。Spotify が提唱したもので、「正しいやり方を、最も楽なやり方にする。ただし、それだけに強制はしない」という考え方を持っています。開発者は Golden Path から外れることもできるけれど、それに従えばセキュリティや監視やデプロイが自動的に整った状態でスタートできる。ルールではなく、舗装路（Paved Road）だということです。また Platform as a Product という視点も重要で、社内向けのツールであっても開発者体験と継続的な改善を考えることがこの職の特徴だと思います。

自分の志向との重なり

自分がこの領域に関心を持つ理由を整理すると、次のことが言えます。

システムの中での責任の分離と、ミスを犯しにくい構造を事前に設計しておくことに、一貫した関心があります。「動くものを作る」こと以上に「どういう構造にすればミスが起きにくいか」「どの層が何を保証するか」を考えることに面白さを感じています。

それをもっと具体的なイメージで言うと、「自分が最強のデプロイ基盤を作る。あとはその上で何でも作っていい」という状態を達成したい気持ちがあります。スケーリングや安全性の保証をプラットフォーム側に閉じ込め、その設計を自分が引き受ける。他のエンジニアが基盤を意識せずに動けるようになる状態です。そこには技術的な面白さと、ユーザー体験向上に直接関われることへの喜びの両方があります。

研究室サーバー上での PoC アプリの大量デプロイ基盤を構築した経験が、この志向を一番よく表していると思います。開発者には Dockerfile と entrypoint.sh だけを書いてもらい、Traefik によるルーティング・HTTPS・デプロイ手順・障害時の挙動はプラットフォーム側で担う設計にしました。「開発者が何をして良くて、何をしてはいけないか」の境界を設計することが、自分の作業の中心でした。

この志向は Platform Engineering の思想と重なる部分が大きいと感じています。

自分のやりたいこと

自分は、学術と産業の橋渡しをソフトウェアエンジニアリングの観点から取り組むことに興味があります。アーキテクチャ設計やエンジニアリングの観点から先進技術の標準化を主導すること、一人で完結した開発を行うのではなく、誰かと一緒により良い仕組みを作っていくことが、自分のやりたいことに近いと思っています。

Platform Engineer という職はその志向と重なる部分が大きいですが、唯一の答えというわけではありません。今は「この方向はありかもしれない」という位置づけで考えています。

近いうちに Clean Architecture を読んでみます。

Clean Architecture 達人に学ぶソフトウェアの構造と設計

アーキテクチャのルールはどれも同じである! どんな種類のシステムでもソフトウェアアーキテクチャのルールは同じ。ソフトウェアアーキテクチャのルールとは、プログラムの構成要素をどのように組み立てるかのルールである。時代を超越した不変のルールたちを紹介する。

tatsu-zine.com

松本 侑真 — #docker

Uvicornを用いたFlaskの本番起動について

想定する基本的なディレクトリ構成#

アプリ開発時のFlaskの起動方法#

本番環境でのFlask起動方法#

Uvicornを用いたFlaskの起動#

Traefikをリバースプロキシとして利用する#

Traefikのルーティングに対応させたミドルウェア設定#

PrefixMiddleware でやっていること#

パスの処理はTraefikとFlaskのどちらで行うべき？#

（余談）WSGIとASGIの違い#

Platform Engineerに関して

要約#

Platform Engineeringとは何か#

自分の志向との重なり#

自分のやりたいこと#

松本侑真 — #docker

想定する基本的なディレクトリ構成

アプリ開発時のFlaskの起動方法

本番環境でのFlask起動方法

Uvicornを用いたFlaskの起動

Traefikをリバースプロキシとして利用する

Traefikのルーティングに対応させたミドルウェア設定

PrefixMiddleware でやっていること

パスの処理はTraefikとFlaskのどちらで行うべき？

（余談）WSGIとASGIの違い

要約

Platform Engineeringとは何か

自分の志向との重なり

自分のやりたいこと