私はどちらも毎日使っています。Ollama はラップトップとオフィスの GPU ワークステーションで動いていて、開発と自分用のツールに使っています。vLLM はフリーランスの案件で、96 GB の GPU 一枚からチャットモデルを配信しています。最初は Docker Compose で、今は小さな Kubernetes クラスタの上です。

vLLM と Ollama の比較表

#

Ollama とは

#

自分のマシンでモデルに答えさせる方法として、Ollama は私の知る限りいちばん簡単です。llama.cpp の上に作られていて、量子化された GGUF モデルを動かします。8B のモデルが約 5 GB に収まり、MacBook でも快適に動くのはそのためです。モデルを名前で pull すると、最初に呼び出したときにロードされ、5 分間何もすることがなければメモリから外れます。なので、ほかに動かしているものと行儀よくマシンを分け合ってくれます。

その行儀の良さがトレードオフです。Ollama は一度に一人を相手にする前提で作られています。デフォルトでは一度に 1 リクエストしか処理せず、OLLAMA_NUM_PARALLEL でスロットを増やせますが、スロットひとつごとにコンテキスト 1 つ分のメモリを食いますし、何十人ものユーザーを一枚の GPU にバッチでまとめるためのものでは、もともとありません。

vLLM とは

#

vLLM はサービングエンジンで、まさにそのバッチ処理のために作られています。それを支えているのは主に二つのアイデアです。PagedAttention は、リクエストごとの KV キャッシュ(モデルがトークンを読み書きしながら積み上げていく attention の状態)を小さな固定サイズのブロックに格納するので、パディングや断片化で GPU メモリが無駄になりません。連続バッチ処理では、新しいリクエストが今のバッチの終わりを待たずに、生成ステップの合間にバッチへ加わります。この二つのおかげで、vLLM を動かした GPU 一枚は、同じ GPU でリクエストを一件ずつ処理するよりはるかに多くの同時ユーザーをさばけます。両者を自分で比較計測したことはないので、この記事にはスループットの数字がありません。この主張を実測したものとしては、Red Hat の Ollama vs. vLLM ベンチマークがあります。A100 一枚で Llama 3.1 8B を同時ユーザー 1 から 256 まで試したもので、OLLAMA_NUM_PARALLEL を 32 まで上げても、vLLM のピークが毎秒約 793 出力トークンに対して Ollama は 41 でした。

代償として、vLLM はカードを自分のものだと思っているかのように振る舞います。起動時に GPU メモリの取り分を確保し、重みに要らない分を KV キャッシュで埋め、誰も呼び出していなくても全部を握ったままです。それに、必要なのは Hugging Face のフルの重みか、FP8 や AWQ のような GPU 向けの量子化です。GGUF ファイルも読み込めはしますが、vLLM 自身のドキュメントがその対応を「highly experimental and under-optimized」と呼んでいるので、Ollama でダウンロードしたものを使い回すつもりではいないほうがいいです。

必要な GPU メモリの目安

#

重みだけのおおよそのサイズです。

16 ビットならパラメータあたり約 2 バイト、8 ビットなら 1 バイト、Q4_K_M なら 0.5 バイトを少し超えるくらいです。重みに加えて KV キャッシュが乗り、これはコンテキスト長と処理中のリクエスト数に応じて増えます。同じモデルでも、50 人に配信する vLLM のほうが、あなた一人に応える Ollama よりずっと多くのメモリを必要とするのは、この二つ目の部分のせいです。

API はひとつ、サーバーは二つ

#

どちらも OpenAI の chat completions API を公開しているので、私のコードは相手がどちらなのかを知りません。URL とモデル名は環境変数から取ります。

import os
from openai import OpenAI

# ラップトップ: LLM_URL=http://localhost:11434/v1  LLM_MODEL=qwen3:8b
# GPU サーバー: LLM_URL=http://localhost:8000/v1   LLM_MODEL=qwen3-8b
client = OpenAI(base_url=os.environ["LLM_URL"], api_key="not-needed")

reply = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "Say hello in Korean."}],
)
print(reply.choices[0].message.content)

大きな GPU のないラップトップでは、アプリは Ollama を向きます。サーバーでは vLLM を向きます。ほかは何も変わらず、GPU マシンの電源が入っていなくてもアプリを開発できます。vLLM 側では --served-model-name でモデルに短い名前を付けておけば、クライアントが Hugging Face のフルパスを送らずに済みます。

忘れやすいので、注意をひとつ。同じモデルでも、両者で同じ答えが返るわけではありません。Ollama の qwen3:8b は 4 ビット量子化ですが、vLLM では普通 16 ビットか FP8 の重みを動かします。片方に合わせて調整したプロンプトが、もう片方では違う振る舞いをすることがあります。なので測っているものは、回答の品質であれ、拒否であれ、JSON がパースできるかどうかであれ、本番で実際に使うサーバーで確かめる必要があります。

Ollama のインストール方法

#

Mac か Windows なら、ollama.com からアプリをダウンロードします。Linux ならこうです。

curl -fsSL https://ollama.com/install.sh | sh
ollama run qwen3:8b

これで終わりです。API は http://localhost:11434 で使えるようになっていて、OLLAMA_HOST を設定しない限り localhost でしか待ち受けません。それが望ましい挙動です。私の Ollama はオフィスのワークステーションで 127.0.0.1 にバインドして動いていて、どこからでもトンネル経由で届くようにしています(Cloudflare WARP でそれを組んだ方法)。

vLLM のインストール方法

#

NVIDIA の GPU と新しめのドライバーがある Linux なら、こうです。

python -m venv .venv && source .venv/bin/activate
pip install vllm
vllm serve Qwen/Qwen3-8B --served-model-name qwen3-8b --max-model-len 16384

初回の実行では Hugging Face から重みをダウンロードします。ログに Application startup complete と出たら、curl localhost:8000/v1/models でモデルが一覧に出て、上の Python がそのまま動きます。

Docker で vLLM を動かす

#

ずっと動いていてほしいものには、pip install ではなく公式イメージを使っています。主な理由は、CUDA、PyTorch、vLLM がセットで固定された状態で手に入るからです。汎用的な Compose のサービスはこうなります。

services:
  vllm:
    image: vllm/vllm-openai:v0.30.0   # 私が使ったタグ。今の最新版を固定すること。イメージは約 30 GB
    restart: unless-stopped
    ipc: host                          # PyTorch が共有メモリを必要とする
    command: >
      --model Qwen/Qwen3-8B
      --served-model-name qwen3-8b
      --gpu-memory-utilization 0.85
      --max-model-len 16384
    volumes:
      - ${HOME}/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "127.0.0.1:8000:8000"          # LAN ではなく ssh -L 経由でアクセスする
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 10s
      timeout: 5s
      retries: 90
      start_period: 120s

タグは固定してください。vLLM は動きが速く、リリースのたびにフラグやデフォルトが変わります。それがいつ起きるかは、自分で決められるようにしておきたいところです。ipc: host(あるいは十分な shm_size)は vLLM 自身の Docker の手順に書かれています。長い start_period が必要な理由は、次の節のひとつ目です。

vLLM の運用でハマったこと

#

起動に数分かかる

#

重みのロード、コンパイル、CUDA グラフのキャプチャで、私のサーバーでは 190 秒かかりました。大きなモデルなら 3〜5 分は普通です。Web アプリ向けに書いたヘルスチェックだと、準備ができる前に殺してしまいます。Compose なら長い start_period、Kubernetes なら startup probe が必要です。それに、再起動のたびにモデルのいない時間が数分できるので、気軽に再起動するものではありません。

GPU メモリは、与えた分を起動時に持っていく

#

--gpu-memory-utilization は vLLM が使ってよいカードの割合で、最近のリリースのデフォルトは 0.92、重みに要らない分はすべて KV キャッシュになります。vLLM がカードを独り占めしているなら、それで問題ありません。私の場合はそうではなく、横で小さなモデルが動いているので、96 GB のカードで 0.70 にしています。モデルは FP8 の 35B の mixture-of-experts で、ロードすると 47.7 GiB、KV キャッシュには 15 GiB が残りました。16k のコンテキストなら十分な量です。最大シーケンス長が KV キャッシュに収まらないと言って vLLM が起動を拒むなら、大きな GPU を探しに行く前に --max-model-len を下げてみてください。

LoRA のスロットは先にメモリを取る

#

vLLM はひとつのベースモデルに複数の LoRA アダプターを載せて配信でき、リクエストごとにモデル名で切り替えられます。これは Ollama には実質できないことです。ただし vLLM は起動時に、ランク --max-lora-rank のアダプター --max-loras 個分の領域を確保します。mixture-of-experts のモデルではこの確保がエキスパートにも及ぶので、すぐに膨らみます。0.70 では、ランク 64 のアダプター 4 つは収まりませんでした。2 つなら収まりました。

デフォルトのシーケンス上限がハイブリッドモデルに合わなかった

#

私が配信しているモデルは attention の層に Mamba 系の層が混ざっていて、シーケンスごとにその層用のキャッシュブロックがひとつずつ必要です。vLLM の --max-num-seqs のデフォルトは 70 GB 以上のカードで 1024(それ未満では 256)なので、そのカードでは起動に失敗し、--max-num-seqs 256 で直りました。新しめのアーキテクチャが起動しないときは、もっと込み入った原因を疑う前にこのフラグを確認してください。

vllm という名前の Kubernetes Service で vLLM がクラッシュする

#

これが個人的にいちばん気に入っています。Kubernetes は namespace 内のすべての Service について、その名前を元にした環境変数を注入します。なので vllm という Service があると、すべての Pod に VLLM_PORT=tcp://<cluster-ip>:8000 が渡ります。vLLM は VLLM_PORT を自分の設定のひとつとして読み、そこにある URL を解釈できずに落ちました。もちろん、モデルを丸ごとロードしたあとでです。なので試すたびに 3 分かかりました。vLLM のドキュメントにはこの注意がちゃんと書いてあって、私はそれを後から見つけました。直し方は、Pod に enableServiceLinks: false を付けるか、Service を別の名前にすることです。

動く Deployment の骨格を、大事な部分だけに絞って載せます。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm
spec:
  replicas: 1
  strategy:
    type: Recreate               # 先に古い Pod が GPU を解放する必要がある
  selector:
    matchLabels: {app: vllm}
  template:
    metadata:
      labels: {app: vllm}
    spec:
      enableServiceLinks: false  # Service 由来の VLLM_PORT=tcp://... を入れない
      containers:
        - name: vllm
          image: vllm/vllm-openai:v0.30.0
          args: ["--model=Qwen/Qwen3-8B", "--served-model-name=qwen3-8b"]
          resources:
            limits:
              nvidia.com/gpu: "1"
              memory: 32Gi       # ロード時は配信時よりはるかに多くのホスト RAM が要る
          volumeMounts:
            - {name: shm, mountPath: /dev/shm}
          startupProbe:          # モデルがロードされるまでは判定しない
            httpGet: {path: /health, port: 8000}
            initialDelaySeconds: 120
            periodSeconds: 10
            failureThreshold: 90
          livenessProbe:         # 再起動はフルリロードになるので気長に待つ
            httpGet: {path: /health, port: 8000}
            periodSeconds: 30
            timeoutSeconds: 5
            failureThreshold: 10
      volumes:
        - name: shm
          emptyDir: {medium: Memory, sizeLimit: 16Gi}

真似する価値があるのはプローブの部分です。startup probe は 2 分待ってから、さらに 15 分、モデルが上がってくるのを待ち、それでもだめなら Kubernetes が死んだと判断します。liveness probe が再起動するのは、失敗が 5 分ほど続いてからです。負荷の高いエンジンでは /health が遅くなることがあり、どのみち再起動はフルリロードになるからです。GPU 一枚の環境では Recreate が効いてきます。ローリングアップデートは新しい Pod を先に起動するので、新しい Pod は古い Pod が握ったままの GPU を待って止まってしまいます。メモリの上限が大きく見えるのは、実際に大きいからです。重みが GPU に載ってしまえば、私の環境ではホスト RAM は約 7 GiB に落ち着きますが、ロードそのものにはもっとずっと多く必要です。

Ollama について知っておきたいこと

#

驚かされることは少なめです。主に、やっていることが少ないからです。

しばらく静かだったあとの最初のリクエストは遅くなります。モデルがアンロードされていて、もう一度ロードしなければならないからです。OLLAMA_KEEP_ALIVE は、最後のリクエストのあとモデルがどれだけメモリに残るかを決めます。その待ち時間が気になるなら値を上げるか、ほかに何もしないマシンなら -1 にしてください。

コンテキストウィンドウは GPU メモリの量で変わります。24 GiB 未満だと Ollama のデフォルトは 4k トークンで、ほとんどのモデルが対応している長さよりずっと短く、収まらないプロンプトはエラーにならずに黙って切り詰められます。長いプロンプトの冒頭が無視されているように見えたら、OLLAMA_CONTEXT_LENGTH(またはリクエストごとの num_ctx)を実際に必要な長さに設定してください。

リモートの Ollama をラップトップにフォワードするなら、11434 は避けてください。Ollama のデフォルトのポートなので、ローカルの Ollama がいつか起動すると二つがポートを奪い合い、気づかないまま違うほうと話していた、ということになりかねません。私は 11435 にフォワードしています。

それから、Ollama はマルチユーザーのサーバーではありません。数人が使う社内ツールなら問題ありませんが、本当に同時アクセスが出てきたら、そこが vLLM に移るタイミングです。

どちらを使うか

#

自分のマシンでモデルを動かしたいなら、Ollama をインストールしてそこで終わりにしてください。10 分もあれば何かが答えてくれるようになります。GPU サーバーがあって、それを一日中呼び出すユーザーやアプリがいるなら vLLM を使い、遅い起動と持っていかれるメモリを受け入れて、プローブをきちんと設定してください。結局両方を使う構成も多く、私のところもそうです。コードを書く場所には Ollama、リクエストが届く場所には vLLM です。

ほかの選択肢もあります。vLLM の代わりによく挙がるのは SGLang ですが、本番で動かしたことはないので、推測で書くよりは外しておきました。モデルをスマホで動かす必要があるなら、それはまた llama.cpp の出番で、これについては React Native でオンデバイスの LLM を動かす記事に書きました。

GitHub ActionsでDocker Composeを動かす方法を探してここに来たなら、先に結論を。私はそれを2年やって、やめました。いまのCIは同じPostgresとValkeyのイメージをservices:として宣言し、同じuv run …とnpm run …をランナー上で直接実行します。Composeは開発者が手元で動かすものに戻りました。以下はその理由と、実際のファイルです。

2024年にCI/CDのロジックはプラットフォーム固有のYAMLではなくDocker Composeにという記事を書きました。ビルドのロジックはComposeに置き、CIツールにはそれを呼ぶことだけをさせる、という内容です。2年たって、実際にリリースに使っているリポジトリを全部見直しました。ワークフローがあるのは4つで、コミッターはどれも私一人です。そして、そのワークフローのうちdocker composeを呼んでいるものは、もう一つもありません。原則は残り、やり方は残りませんでした。以下はその代わりに入ったものです。ファイルを削って例にしたもの、GitHubが記録したステップごとの所要時間、そしてCI/CDの図が期待するほどには自動化されていない部分も書いています。

動かしているパイプラインを一つの表に

#

教科書の言葉でいえば、二つのHugoサイトは継続的デプロイメントで、アプリ（私が作っているマーケットプレイス兼コミュニティアプリ）は継続的インテグレーションにコマンド一つのリリースを足した継続的デリバリーです。チェックは何かがおかしいと教えてくれるだけで、デプロイを止めはしません。これは意図してそうしています。OTAアップデートは対象のバイナリバージョンを使っているすべての端末に届くので、マージの副作用ではなく判断であるべきです。そしてAPIはデータベースのマイグレーションが走る場所です。残り二つのDjangoアプリには、ワークフローがそもそもありません。

CIの側：ワークフロー一つ、ジョブ二つ

#

アプリのCIは.github/workflows/checks.ymlというファイル一つです。10月11日までは、これすらありませんでした。以下はその形を削って例にしたものです。

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

二つのジョブは並行して走ります。これまでに成功した35回の実行で、アプリのジョブの中央値は約7分、Pythonのジョブは約12分半です。

services:ブロックが、Composeファイルの移った先です。これは次の節で書きます。環境変数はいくつかとフラグ一つだけです。ほかはすべて開発者がdocker compose upで得る開発用のデフォルトに落ちるので、テストにシークレットは一つも要りません。本当にそうか確かめるために、まさにその環境だけで、ほかに何もない状態でテストの一部を走らせました。

CIは手元のノートPCや本番イメージと同じインタープリタ、つまりuv自身がビルドしたPython 3.15.0で動きます。uv syncが.python-versionを読み、まさにそのビルドをダウンロードするからです。（実際のファイルではsetup-uvにpython-version-fileという入力も渡していますが、これは何もしていません。setup-uv v6にはそんな入力がなく、毎回の実行にそういう警告が付いています。この記事を書いていて初めて気づきました。）

インタープリタを揃えた甲斐は、ワークフローを入れて8日後に出ました。10月19日に3.15のJITコンパイラを有効にしたところ、有効にして最初の実行でテストが一つ落ちたのです。アプリが保存のたびに通るコードパスのごく普通のyield fromが、AttributeError: 'list' object has no attribute 'send'を投げていました。同じコミットをJITなしで走らせると通ります。私のMacはarm64で一度もこれに当たらず、ランナーは本番マシンと同じx86_64です。JITはCIでもDockerfileでも再び無効にしてあり、このバグが本番に届くことはありませんでした。これはpython/cpython#155823で、3.15.0のリリース後の10月13日に上流で修正されています。

実は最初の実行も落ちていて、こちらの理由はもっと地味です。Expoはexpo startのときにexpo-env.d.tsを書き出し、このファイルはgitignoreされています。なので私が使ってきた作業コピーにはどれもあり、まっさらなチェックアウトにはありませんでした。TypeScriptは、ローカルでは一度も出たことのないエラーを五つ出しました。そのファイルを書き出すステップが対処です。

concurrencyは、同じブランチに新しいpushが来ると前の実行を取り消します。これまでに取り消された12回は、すべてこれによるものです。コミット前のフック（pre-commit）がリンターを走らせ、PythonかTypeScriptがステージされていれば型チェッカーも走らせるので、ミスの大半はpushまで行きません。

Docker Composeファイルはどこへ行ったか

#

アプリのdocker-compose.ymlのうち、CIに関係する部分を例にしたものです。実物にはもっと多くのサービスと、ずっと多くの環境変数があります。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.ymlのservices:ブロックと並べると、同じイメージが二つです。Postgres 17（こちらはAlpine版、CIはDebian版）とvalkey/valkey:8-alpine。いまの関係はこうです。Composeファイルは開発者が動かすもの。CIは同じイメージをサービスコンテナとして宣言し、開発者が打つのと同じコマンド、uv run …とnpm run …をランナー上で直接実行します。

2024年の記事と比べると、いちばん大事にしていた部分は残りました。CIツールは薄く、チェックもデプロイも自分で実行できるコマンドです。残らなかったのは、CIからComposeを呼ぶやり方です。

アプリのCIはDockerイメージをまったくビルドしません。イメージはデプロイのときにFlyのビルダーが一度だけビルドし、CIはコードが大丈夫かどうかだけ答えればよく、ツールチェーンがキャッシュされていればそれは6秒のインストールで済みます。それにComposeファイルは作業コピーをバインドマウントし、データを投入しますが、それはテストの実行がすることではありません。CI用に別のComposeファイルが必要になっていたはずで、それは同じサービスの二つ目の定義を手で揃え続けるということです。

そして2024年の例には、当時気づかなかったバグがありました。docker compose buildはイメージをビルドするだけで、サービスのcommandは実行しません。なので、あのファイルのnpm testはCIで一度も走っておらず、ワークフローはテストが通ろうが落ちようが緑でした。

あの記事がいちばん心配していたリスク、つまりCIベンダーの乗り換えは、結局起きませんでした。実際に起きた移行は反対側でした。このブログとクライアントのサイトがホスティング先をCloudflare Pagesに移し、ブログのほうは45行のワークフローを一つ新しく書くだけで済みました。ビルドがもともとコマンド一つだったからです。それから、私が警告していた300行のワークフロー。一つあります。pyhtml2textのものです。wheelをLinux、macOS、Windowsのランナーで、それぞれ複数のアーキテクチャ向けにビルドしなければならないので長いのですが、だからこそプラットフォーム固有のYAMLが正しい道具になる唯一の仕事でもあります。

キャッシュ：まずステップの所要時間を読む

#

GitHubはすべてのステップの所要時間を記録していて、gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobsで取り出せます。以下は10月20日の、アプリで最新の成功した実行です。

依存関係のキャッシュは二つとも有効で、どちらも安い部分です。GitHubがこのリポジトリ用に保持しているuvのキャッシュは200KBほどで、setup-uvがダウンロードし直せば済むものを整理してしまうからです。npmのほうは400MB近くあります。時間がかかっているのはテストで、テストはすでに4並列で走っています。実行を速くしたいなら、キャッシュではなくテストスイートに手を入れます。

ブログは正反対です。Hugoが処理した画像はgitignoreされたresources/_genにあるので、新しいランナーのたびにカバー、本文の画像、プレースホルダーを全部エンコードし直していました。後で載せるワークフローはactions/cacheでこれを復元します。キーは画像そのもののハッシュで、合わなければいちばん新しい古いキャッシュで代用します。Hugoは足りない分しか処理しないからです。キャッシュ導入前の最後の8回では、ビルドのステップに33〜76秒かかっていました。導入後の26回は6〜20秒で、例外は94秒の一回だけ。しかも同じコミットでプレースホルダーと二つ目のカードサイズを追加したうえでの数字です。

アプリのイメージはFlyのビルダーでビルドされ、依存関係のファイルをコードより先にコピーし、uvのダウンロードキャッシュはBuildKitのキャッシュマウント（RUN --mount=type=cache,target=/root/.cache/uv）に置いています。ただ、もっと大きな改善はキャッシュではありませんでした。以前の.dockerignoreはブロックリストで、追加のgit worktreeを置いたフォルダーを漏らしていました。それぞれが自分の依存関係とビルド成果物を抱えています。そのせいで27万7千ファイル、7.7GBが、デプロイのたびにビルダーへ送られていました。許可リストに書き直したいま、ビルドコンテキストは40MBほどです。パターンの例はこうです。

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

シークレットはできるだけ少ない場所に

#

シークレットは三か所にあります。GitHub Actionsのシークレットはワークフローがすることのためのもので、二つのHugoリポジトリにはそれぞれCLOUDFLARE_API_TOKENが一つあるだけです。Flyのシークレットはアプリの実行時設定で、flyctl secrets setで入れ、Actionsを経由することはありません。そしてノートPCのgitignoreされた.envに、デプロイスクリプトがCloudflareのキャッシュを消すときに使うトークンがあります。

PyPIにはシークレットがそもそも要りません。pyhtml2textはトラステッドパブリッシングを使っています。GitHubがワークフローに発行する短命のOIDCトークンをPyPIが受け付けるので、リリースのジョブはid-token: writeを求めるだけで、リポジトリのシークレットのページは空です。漏れるものも、ローテーションするものもありません。

トークンには必要な分だけを与えます。GitHubにあるアプリのFlyトークンは、マシンの一覧を取るだけの定期チェック用なので、fly tokens create readonlyで作っています。Pagesのデプロイが求めるのはcontents: readとdeployments: writeだけで、それ以上はありません。

入力は直接スクリプトに入れず、必ずenv:を通します。OTAのワークフローは自由記述のリリースノートを受け取ります。これをrun:の中に${{ inputs.notes }}と書くと、bashが読む前にテキストがスクリプトにそのまま貼り込まれるので、引用符とセミコロンを含むノートはコードになってしまいます。環境変数として渡せば、データのままです。パターンの例です。

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

GitHubの外に置いたままのキーもあります。ある定期レポートには、アプリのサインイン基盤に対する管理者権限を持つキーが必要です。なのでそのレポートは定期ワークフローから、Mac上の定期ジョブに移しました。ワークフローは手動の予備として残してあり、そのキーが要るセクションを除いて投稿します。

デプロイ：pushごとに、スクリプトで、タグで

#

Hugoサイトはpushのたびにデプロイ

#

ブログのワークフローを例にしたものです。初回だけPagesのプロジェクトを作るステップは省いています。

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }}によってmainが本番になり、ほかのブランチはどれもプレビューURLを得ます。クライアントのサイトのワークフローはこれと同じ形で、ビルドの前にrm -rf publicが一行加わっています。あちらはpublic/がコミットされているので、そうしないと削除したページがアップロードに残り続けるからです。

Hugoのバージョンはここでだけ固定しています。10月にパッケージマネージャーのアップグレードでノートPCのHugoが0.168に上がりましたが、これはテーマが対応する最新版より一つ新しいものです。デプロイは0.165のままで、何も起きませんでした。

そして、ビルドそのものがテストです。9月14日、あるブランチのプレビューデプロイが3回続けて失敗しました。そのブランチの記事が、Hugoのrefでまだ下書きの記事を指していたのです。CIは本番と同じように下書きを除いてビルドするので、リンク先は存在せず、HugoはREF_NOT_FOUNDで止まりました。その間もmainは普通にデプロイされ続けていました。

アプリのAPIはスクリプトでデプロイ

#

デプロイスクリプトの中心部分を例にしたものです。

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

そしてfly.tomlの対応する部分です。

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

イメージは一度だけビルドし、コミットと時刻からなるラベルを付けてFlyのレジストリに送り、そのラベルでデプロイします。なので、ロールアウトされるのはビルドしたものそのものです。

ゼロダウンタイムを実現しているのは、先に予備のマシンを起こしておくことです。max_unavailable = 1が数えるのは動いているマシンだけですが、アプリは暇なときに動いているマシンを一台も置きません（サスペンドしたマシンは1秒ほどで復帰します）。そのため、起きていた一台が寝ているマシンと同じバッチで置き換えられ、後ろに温まったマシンが一台もない、ということが起きていました。9月28日にオリジンへプローブを送り続けて測ったところ、素のflyctl deployではタイムアウトが7回と7.3秒の空白があり、先にビルドしてロールアウト開始時にはマシンを一台起こしておくスクリプトのデプロイでは、2,514リクエストで失敗はゼロでした。

スクリプトの残りは、エラーの通知が届くチームのチャットチャンネルにデプロイの印を残します。エラーが固まって出たとき、直前に何が変わったかと照らし合わせられるようにです。それからCloudflareのキャッシュを消し、マシンを温めておきます。Webフロントエンドはイメージをまったく通りません。それはフロントエンドとバックエンドを別々にデプロイするに書きました。

マイグレーションはパイプラインのステップではありません。Flyのrelease_commandが私の環境では固まってしまったので、新しいイメージで最初に起動したマシンがロックを取ってマイグレーションし、ほかのマシンは待ちます。そのため、どのマイグレーションもまだ動いているコードと両立しなければなりません。カラムはあるデプロイで追加し、次のデプロイで使うのをやめ、三回目のデプロイで削除します。

このスクリプトに、私のノートPCでなければならない部分は特にありません。ただ、ノートPCにしかないファイルがいくつかあって、それが縛りになっています。Cloudflareの認証情報と、最後に何をデプロイしたかの記録で、まっさらなランナーにはこれがありません。コミットしていない変更もデプロイしてしまい、チャットでそう知らせますが、Webのリリース用スクリプトは汚れた作業ツリーを拒否します。

ブランチごとのプレビュー環境で私は、これを手でやるのは自分一人なら構わないが、二人目の開発者からはgitで何かが起きたから起きるようにしなければならない、と書きました。アプリの開発者はまだ一人です。あの記事のブランチ環境のワークフローは、作ったときのブランチにそのまま置いてあります。

OTAのワークフローは手動専用です。公開は判断であるべきですし、アップデートのサービスは部分ロールアウトが開いている間は新しいリリースを拒むので、pushトリガーではカナリアのたびに引っかかってしまいます。このワークフローは一度も実行されたことがありません。これまでのOTAアップデートはすべてノートPCから、ワークフローが呼ぶのと同じスクリプトで出しています。薄いワークフローにする理由は一言でこれです。リリースをどう始めても、同じスクリプトです。

pyhtml2textはタグでリリース

#

リリースのジョブです。パッケージ名は一般的なものにしてあります。

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

リリースのジョブはすべてのビルドジョブを待ち、実際に公開するのはタグのときだけです。手動実行はビルドとアテステーションまではしますが、何もアップロードしません。actions/attestはどのワークフローが各wheelをビルドしたかを記録し、uv publish --trusted-publishing alwaysはパスワードの代わりにOIDCトークンでアップロードします。パッケージそのものについては閉じられたプルリクエスト、フォーク、そしてPyPIパッケージに書きました。

定期ワークフローはベストエフォート

#

アプリには定期ワークフローが一つあります。Flyがベースラインより多くのマシンを起動していないかを見るチェックで、放っておけば請求書で初めて気づくことです。通知はわざと失敗することで行います。定期実行が失敗すると、GitHubが所有者にメールを送るからです。

設定はcron: '*/15 * * * *'、1日96回です。ところがこの2週間は1日3〜8回しか動いておらず、実行間隔の中央値は3時間40分ほどでした。GitHubのドキュメントが挙げる理由は負荷だけです。Actionsが混んでいると定期実行は遅れることがあり、混み具合によっては落とされることもある、と。持続的なスケールアウトを見るなら数時間で十分です。数分以内に鳴らなければならないものにとって、GitHubのcronは監視ではありません。

パイプラインに投げかけたい質問

#

これから作る人も、すでにあるものを見直している人も：

1. GitHub Actionsが丸一日止まったら、それでもリリースできますか？ できないなら、リリースのロジックがYAMLの中にあるということで、2024年の記事がまだ当てはまります。
2. CIは本番と同じインタープリタ、同じCPUアーキテクチャ、同じデータベースのメジャーバージョンで動いていますか？ 私のCIがコンパイラのバグを捕まえられたのは、ランナーと本番がどちらもx86_64で、ノートPCがそうではなかったからです。
3. まっさらなチェックアウトで通りますか？ 通らないとしたら、たいていは生成されてgitignoreされたファイルのせいです。
4. 実行時間は実際どこに使われていますか？ キャッシュを足す前に、ステップの所要時間を読んでください。
5. シークレットはそれぞれ何か所にありますか？ そして本当にGitHubに置く必要がありますか？

ビルドやテストの手順をGitHub ActionsのYAMLに直接書いているチームは多いと思います。それで普通に動くのですが、同じビルドを手元のマシンで実行したくなったり、「GitLabに移行しようか」という話が出たりした瞬間に、パイプライン全体が特定ベンダーの設定形式にがっちり溶接されていることに気づきます。私のやり方はかなり地味です。本当のロジックはDocker Composeに置いて、CIツールにはそれを呼び出すことだけをさせます。

ビルドロジックをActionsのYAMLに書かない理由

#

わかりやすい問題はロックインです。ActionsのワークフローはGitLabにもBitbucketにもJenkinsにも通用しないので、ビルド手順がワークフローファイルの中にあると、プラットフォームを変えるときに全部書き直しです。その作業に工数を確保するチームを、私はまだ見たことがありません。

もうひとつ、地味に効いてくる問題があります。パイプラインをローカルで実行できないことです。ビルドの変更を試す方法が「コミットをプッシュしてActionsのタブを眺める」しかないと、gitの履歴が「fix ci」「fix ci again」「頼む」で埋まっていきます。Composeファイルなら手元でもランナー上でも同じように動くので、「自分のマシンでは動くんですけど」という議論も始まる前にほぼ消えます。

そしてYAMLは育ちます。最初は整った20行だったものが、キャッシュの工夫や条件分岐が加わって300行になり、開発者はGitに加えてCIの方言まで覚えるはめになります。ひとつのスクリプトはひとつのことをやるべきなのに、巨大なワークフローファイルは全部を一度に抱え込みがちです。

Composeを使うと、この分担がきれいになります。ビルドとテストはComposeファイルの責任、CIプラットフォームはプッシュのたびにそれを実行するだけの存在です。

セットアップ

#

1. まずDockerfileを用意して、イメージのビルド方法の置き場所をひとつに絞ります:

# 公式のNode.jsランタイムをベースイメージとして使用
FROM node:14

# コンテナ内の作業ディレクトリを設定
WORKDIR /app

# package.jsonとpackage-lock.jsonファイルをコンテナにコピー
COPY package*.json ./

# 依存関係をインストール
RUN npm install

# 残りのアプリケーションコードをコンテナにコピー
COPY . .

# アプリが実行されるポートを公開
EXPOSE 3000

# アプリケーションを実行するコマンドを定義
CMD ["npm", "start"]

2. 次に、ビルドとテストに必要なサービスを定義するdocker-compose.build.yamlを作ります。

   services:
     app:
       image: myprivaterepo.com/image:latest
       build: .
       volumes:
         - .:/app
       command: sh -c "npm install && npm test"

3. まずはローカルで実行してみます。これこそがこのやり方の狙いです。

   docker compose -f docker-compose.build.yaml build

4. ここまで動けば、GitHub Actionsのワークフロー（他のCIプラットフォームでも同じです）は、処理を呼び出すだけの薄いオーケストレーターになります。

   name: CI/CD Pipeline
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v1
         - name: Build and Test with Docker Compose
           run: docker compose -f docker-compose.build.yaml build
         - name: Push the image referenced in the docker compose file
           run: docker compose -f docker-compose.build.yaml push

これでCIツールの仕事はビルドとプッシュの2つだけになりました。理解する価値のある部分はすべて、どのプラットフォームでも、新しく入ったメンバーでも、そのまま実行できるファイルの中にあります。

イメージのプッシュ

#

Composeファイルのうれしい副作用として、プッシュがとても簡単になります。Dockerはイメージ名からプッシュ先を判断します。image: myprivaterepo.com/image:latestなら、プッシュ先はmyprivaterepo.comです。プライベートレジストリの場合はアクセストークンが必要なので、そこは利用しているレジストリのドキュメントを確認してください。

いまGitHub Actionsで満足しているなら、急いで変える必要はありません。ただ、いつかプロバイダーを乗り換える日が来たとき、移行作業が「300行のYAMLの移植」ではなく「コマンド2つのコピー」で済みます。そしてその日までは、ビルドのデバッグを手元で落ち着いてやれるわけです。