[翻訳] uv による本番環境向け Docker コンテナ

ピン留めされたアイテム

まちゅけん

Hynek 氏の Production-ready Docker Containers with uv の記事を機械翻訳して転載します。

https://hynek.me/articles/docker-uv/

本文章は執筆時のおおよそ 2024-09-04T10:07:09.435795+09:00 辺りの版です。翻訳元が更新される可能性があります。

メタデータ (差分検出用)

テキスト抽出スクリプト

main.py

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "beautifulsoup4>=4.12",
# ]
# ///
import os
from hashlib import sha256
from http.client import HTTPResponse
from pathlib import Path
from reprlib import Repr
from urllib.request import urlopen

from bs4 import BeautifulSoup

URL = "https://hynek.me/articles/docker-uv/"
ENCODING = "utf-8"
SELECTOR = "body > main > div > article > section"


def main() -> None:
    response: HTTPResponse
    with urlopen(URL) as response:
        html_bytes = response.read()
        html_str = html_bytes.decode(ENCODING)

    soup = BeautifulSoup(html_str, "html.parser")
    article_element = soup.select_one(SELECTOR)

    if article_element is None:
        raise ValueError(f"Selector {SELECTOR} not found in {URL}")

    article_str = article_element.get_text("\n")
    article_bytes = article_str.encode(ENCODING)
    article_hash = sha256(article_bytes).hexdigest()
    article_hash_short = article_hash[:7]
    article_file_path = Path(f"article_{article_hash_short}.txt")

    article_file_path.write_text(article_str)

    arepr = Repr(maxstring=os.get_terminal_size().columns, indent=4)
    print(
        arepr.repr(
            {
                "content": article_str,
                "file": str(article_file_path.absolute()),
                "hash": article_hash,
            }
        )
    )


if __name__ == "__main__":
    main()

テキストハッシュ

0de6dabe405b1618dc39e7694616278def2f88ad79481d8c83afe5e7d4aa243d

テキスト

article_0de6dab.txt

uv
 0.3.0
 brought many great features, including support for cross-platform lock files 
uv.lock
. The focus was clearly 
developer experience
 and it shows – it’s a significant leap in Python DX! However, it’s currently lacking one feature that makes it tricky to use 
uv
 in best-practice Docker containers (and 
tox
/
Nox
, but that’s a story for another day): choosing a target virtualenv for 
uv sync
 calls – or supporting 
uv.lock
 for 
uv install
.
I’m aware Astral 
is working on implementing this feature
, so I fully expect this article to be outdated within days or weeks. But I’m seeing excited people hitting walls, other people giving bad advice, and the 
official docs
 not mentioning multi-stage builds. I 
do
 plan to keep this post up-to-date to reflect my own use of 
uv
.
Note that this post assumes you’re running 
uv
 0.3.5 or later. Astral has shipped a 
lot
 of Docker-adjacent features in record time since the initial 0.3.0.
As a reminder, in production, you want the following properties from your Docker workflow:
Multi-stage builds
, so you don’t ship your build tools.
Judicious layering
, for fast builds. Layers should be added in the inverse order they are likely to change so they can be cached for as long as possible.
This also means that dependency installations (what’s in 
uv.lock
) and application installations (what 
you
 wrote) should be strictly separate. While developing, your code is more likely to change than your dependencies.
Bonus: 
build-cache mounts
, so, for example, wheels don’t have to be rebuilt if your dependency layer needs to be recreated.
Bonus: 
byte-compile
 your Python files for faster container startup times.
What I like to do is to build a virtual environment with my application in the 
/app
 directory and then copy it wholesale into the runtime container. This has many upsides, including using the same base containers for different Python versions and virtualenvs coming with 
bin
, 
lib
, and 
share
 directories, making them natural application containers.
In case you wonder why I use virtual environments inside of Docker, 
I wrote it down for you
.
However, it’s tricky with 
uv
 because 
uv install
 doesn’t support 
uv.lock
 files, and 
uv sync
 
always
 uses the virtualenv in the 
current working directory
 called 
.venv
. If it doesn’t already exist, 
uv sync
 transparently creates it, which can lead to shipping empty containers, which is always fun.
It can be worked around by putting the 
.venv
 underneath 
/app
, adjusting the 
$PATH
 variable, and installing your application using 
uv pip
, though.
Important step 0
: Since the name of the virtualenv is always going to be 
./.venv
, make 100% sure that 
.venv
 is in your 
.dockerignore
 file. Otherwise, Docker will copy your local 
.venv
 into the container and you’ll get 
very
 confusing errors, especially if your build operating system differs from the container operating system.
Now, let’s build a web app container together. While I wouldn’t use uWSGI in production anymore as it’s a largely dormant pile of C that has been declared to be in “maintenance mode” by its maintainers, I’ll use it here because it adds build complexities in the form of extra dependencies that you’re likely to encounter in real life, too
1
:
# syntax=docker/dockerfile:1.9


FROM
 ubuntu:noble as build




### Start Build Prep.


### This should be a separate build container for better reuse.




RUN
 <<EOT


set
 -ex




apt-get update -qy


apt-get install -qyy 
\

    -o APT::Install-Recommends
=
false
 
\

    -o APT::Install-Suggests
=
false
 
\

    build-essential 
\

    ca-certificates 
\

    curl 
\

    python3-setuptools 
\

    python3.12-dev


EOT




# Security-conscious organizations should package/review uv themselves.


COPY
 --from
=
ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv




# - Silence uv complaining about not being able to use hard links,


# - tell uv to byte-compile packages for faster application startups,


# - prevent uv from accidentally downloading isolated Python builds,


# - and finally pick a Python.


ENV
 
UV_LINK_MODE
=
copy 
\

    
UV_COMPILE_BYTECODE
=
1
 
\

    
UV_PYTHON_DOWNLOADS
=
never 
\

    
UV_PYTHON
=
python3.12




### End Build Prep -- this is where your Dockerfile should start.




# Prepare a virtual environment.


# This is cached until the Python version changes above.


RUN
 --mount
=
type
=
cache,target
=
/root/.cache 
\

    
set
 -ex 
\

    
&&
 uv venv /app/.venv




# Synchronize DEPENDENCIES without the application itself.


# This layer is cached until uv.lock or pyproject.toml change.


COPY
 pyproject.toml /app


COPY
 uv.lock /app


RUN
 --mount
=
type
=
cache,target
=
/root/.cache 
\

    
set
 -ex 
\

    
&&
 
cd
 /app 
\

    
&&
 uv sync --frozen --no-install-project




# Now install the APPLICATION without any dependencies.


# /src will NOT be copied into the runtime container.


# LEAVE THIS OUT if your application is NOT a proper Python package.


COPY
 . /src


RUN
 --mount
=
type
=
cache,target
=
/root/.cache 
\

    
set
 -ex 
\

    
&&
 uv pip install --python
=
/app/.venv --no-deps /src






##########################################################################




FROM
 ubuntu:noble




# Add the application virtualenv to search path.


ENV
 
PATH
=
/app/.venv/bin:
$PATH




# Don't run your app as root.


RUN
 
set
 -ex 
\

    
&&
 groupadd -r app 
\

    
&&
 useradd -r -d /app -g app -N app




ENTRYPOINT
 
[
"/docker-entrypoint.sh"
]


# See <https://hynek.me/articles/docker-signals/>.


STOPSIGNAL
 SIGINT




# Note how the runtime dependencies differ from build-time ones.


# Notably, there is no uv either!


RUN
 <<EOT


set
 -ex




apt-get update -qy


apt-get install -qyy 
\

    -o APT::Install-Recommends
=
false
 
\

    -o APT::Install-Suggests
=
false
 
\

    python3.12 
\

    libpython3.12 
\

    libpcre3 
\

    libxml2




rm -rf /var/lib/apt/lists/*


EOT




COPY
 docker-entrypoint.sh /


COPY
 uwsgi.ini /app/etc/uwsgi.ini




# Copy the pre-built `/app` directory to the runtime container


# and change the ownership to user app and group app in one step.


COPY
 --from
=
build --chown
=
app:app /app /app




# If your application is NOT a proper Python package that got


# pip-installed above, you need to copy your application into


# the container HERE:


# COPY . /app/whereever-your-entrypoint-finds-it




USER
 app


WORKDIR
 /app




# Strictly optional, but I like it for introspection of what I've built.


RUN
 
set
 -ex 
\

    
&&
 python -V 
\

    
&&
 python -Im site


This doesn’t look terrible; what’s the big deal?
Nothing, really! It’s just a bit awkward to have my virtualenv hidden away in 
/app/.venv
 instead of 
/app/
 
being
 the virtualenv with its 
bin
, 
lib
, and 
share
2
. I also prefer to use absolute paths in my scripts and Dockerfiles and 
/app/.venv/bin/gunicorn
 just doesn’t roll off the tongue like 
/app/bin/gunicorn
.
So, here’s to 
#5229
 – I can wait until my workflow is supported natively, but I hope this was useful to those who want to experiment!
A note on “unpackaged” applications:
 I strongly believe that a Python application should be properly packaged to enjoy the many upsides like resource management using 
importlib
, proper executable scripts using 
project.scripts
 instead of a slapped-on 
scripts
 folder, enjoying the 
upsides of the 
src
 layout
, and the general guardrails of a documented and well-understood structure.
I do understand why Astral added support for unpackaged apps in 
uv
 0.4.0
: if you want to 
go big
, you have to cover all workflows, even the sloppy ones. And I do understand that people are resistant to learn 
another
 concept once things 
finally
 work – although I don’t quite understand the vehemence of the resistance. To be clear: I don’t want them to remove the feature – I just don’t think it’s something to celebrate.
Anyways, if your application isn’t packaged for whatever reason: I have added inline notes how to adjust the Dockerfile. In a nutshell, instead of installing your application in the build step, you 
COPY
 it into the runtime container after 
COPY
ing 
/app
 over. Be careful to not overwrite 
/app
.
P.S. If you need more help with Docker, my friend Itamar Turner-Trauring has 
great resources
 for you.
P.P.S. Don’t ask me about in-dev containers – I don’t know, and I don’t care. The moment I’m forced to use Docker containers in development, I’m switching to goat farming.
I’m using Ubuntu as a base image because that’s what I’m used to. We have our own base images and PPAs outside of Docker, so it makes sense to stick to one platform. Use whatever you want, just for Cthulhu’s sake 
stay away from Alpine
-based ones. The problems it brings is not worth the bunch of megabytes saved. 
↩︎
An older version of this post suggested to add a symlink from 
/app/.venv/bin
 to 
/app/bin
, but that has some unexpected side-effects in how Python discovers its site, so I’ve removed it. 
↩︎

まちゅけん

 uv による本番環境向け Docker コンテナ2024-08-28
uv 0.3.0 では、クロスプラットフォームで使用可能なロックファイル uv.lock のサポートを含む多くの素晴らしい機能が追加されました。開発者の体験（DX）を明らかに重視した内容であり、Python の DX における大きな進歩を感じさせます。しかし、現時点では、ベストプラクティスの Docker コンテナ（および tox/Nox ですが、それについてはまた別の機会に）の中で uv を使用する際にやや厄介な問題があります。それは、uv sync コールにおいてターゲットとなる仮想環境を選択する機能が欠けていること、または uv install において uv.lock をサポートしていないことです。
!Astral がこの機能を実装中であることは承知しているので、この記事の内容は数日から数週間以内に古くなる可能性が高いです。しかし、興奮している人々が壁にぶつかったり、他の人が誤ったアドバイスをしたり、公式ドキュメントがマルチステージビルドについて言及していなかったりするのを目にしています。自分自身の uv の使用に合わせて、この投稿を随時更新する予定です。
この記事は、uv 0.3.5 以降を使用していることを前提としています。Astral は、0.3.0 のリリース以降、Docker に関連する多くの機能を驚異的なスピードで提供してきました。
なお、プロダクション環境では、Docker のワークフローから以下の特性を確保したいと考えています：
マルチステージビルド: ビルドツールを含まないイメージを作成するため。
適切なレイヤリング: ビルドを高速化するためです。レイヤーは、変更される可能性が低い順に追加することで、キャッシュをできるだけ長く活用できるようにするべきです。
これにより、依存関係のインストール（uv.lock 内のもの）とアプリケーションのインストール（あなたが書いたコード）は厳密に分けるべきです。開発中は、コードの変更が依存関係よりも頻繁に発生するためです。
ボーナス: ビルドキャッシュマウント: たとえば、依存関係のレイヤーを再作成する必要がある場合に、ホイールファイルを再ビルドしなくても済むようにするため。
ボーナス: Python ファイルのバイトコンパイル: コンテナの起動時間を短縮するためです。

まちゅけん

私が好んで行うのは、アプリケーションを /app ディレクトリ内に構築し、その仮想環境をランタイムコンテナに丸ごとコピーすることです。これには多くの利点があり、異なる Python バージョンのベースコンテナを共有できる点や、仮想環境が bin、lib、share ディレクトリを含むため、自然な形でアプリケーションコンテナとして利用できる点が挙げられます。

しかし、uv では少し厄介です。なぜなら、uv install が uv.lock ファイルをサポートしておらず、uv sync は常にカレントディレクトリにある .venv という仮想環境を使用するからです。もし存在しなければ、uv sync は透過的にそれを作成しますが、これにより空のコンテナをデプロイしてしまう可能性があり、これがなかなか面白い問題を引き起こします。

この問題は、.venv を /app の下に配置し、$PATH 変数を調整して、uv pip を使用してアプリケーションをインストールすることで回避できます。

それでは、ウェブアプリケーションのコンテナを一緒に作ってみましょう。私はプロダクション環境では uWSGI を使いません。なぜなら、uWSGI は現在「メンテナンスモード」として管理者によって宣言された、ほぼ休止状態の C 言語のコードの塊だからです。しかし、ここではあえて使います。なぜなら、uWSGI は追加の依存関係を必要とし、現実のプロジェクトでも遭遇する可能性が高いため、ビルドの複雑さを増すからです^[1]。

脚注

ベースイメージとして Ubuntu を使用していますが、これは私が慣れているからです。Docker 以外の環境で独自のベースイメージと PPA を使用しているため、プラットフォームを統一するのが理にかなっています。お好みのイメージを使ってください。ただし、お願いですから Alpine ベースのものは避けてください。数メガバイトを節約する代償として引き起こす問題は、その価値がありません。 ↩︎

まちゅけん

# syntax=docker/dockerfile:1.9
FROM ubuntu:noble as build

### ビルド準備開始
### これを別のビルドコンテナに分けることで、再利用性が向上します。

RUN <<EOT
set -ex

apt-get update -qy
apt-get install -qyy \
    -o APT::Install-Recommends=false \
    -o APT::Install-Suggests=false \
    build-essential \
    ca-certificates \
    curl \
    python3-setuptools \
    python3.12-dev
EOT

# セキュリティ意識の高い組織は、自分たちで uv をパッケージ化/レビューすべきです。
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# - ハードリンクが使えない場合に uv が警告しないようにし、
# - uv にパッケージをバイトコンパイルさせてアプリケーションの起動を高速化し、
# - uv が誤って隔離された Python ビルドをダウンロードしないようにし、
# - 最後に、使用する Python を選択します。
ENV UV_LINK_MODE=copy \
    UV_COMPILE_BYTECODE=1 \
    UV_PYTHON_DOWNLOADS=never \
    UV_PYTHON=python3.12

### ビルド準備終了 -- ここから Dockerfile が始まります。

# 仮想環境を準備します。
# これは上記の Python バージョンが変更されるまでキャッシュされます。
RUN --mount=type=cache,target=/root/.cache \
    set -ex \
    && uv venv /app/.venv

# アプリケーション自体を除いた依存関係を同期します。
# このレイヤーは `uv.lock` または `pyproject.toml` が変更されるまでキャッシュされます。
COPY pyproject.toml /app
COPY uv.lock /app
RUN --mount=type=cache,target=/root/.cache \
    set -ex \
    && cd /app \
    && uv sync --frozen --no-install-project

# 依存関係なしでアプリケーションをインストールします。
# `/src` はランタイムコンテナにコピーされません。
# アプリケーションが適切な Python パッケージでない場合は、この部分を省略してください。
COPY . /src
RUN --mount=type=cache,target=/root/.cache \
    set -ex \
    && uv pip install --python=/app/.venv --no-deps /src


##########################################################################

FROM ubuntu:noble

# アプリケーションの仮想環境を検索パスに追加します。
ENV PATH=/app/.venv/bin:$PATH

# アプリケーションを root ユーザーとして実行しないでください。
RUN set -ex \
    && groupadd -r app \
    && useradd -r -d /app -g app -N app

ENTRYPOINT ["/docker-entrypoint.sh"]
# 詳細は <https://hynek.me/articles/docker-signals/> を参照してください。
STOPSIGNAL SIGINT

# ランタイム依存関係がビルド時の依存関係と異なることに注意してください。
# 特に、uv は含まれていません！
RUN <<EOT
set -ex

apt-get update -qy
apt-get install -qyy \
    -o APT::Install-Recommends=false \
    -o APT::Install-Suggests=false \
    python3.12 \
    libpython3.12 \
    libpcre3 \
    libxml2

rm -rf /var/lib/apt/lists/*
EOT

COPY docker-entrypoint.sh /
COPY uwsgi.ini /app/etc/uwsgi.ini

# 事前に構築された `/app` ディレクトリをランタイムコンテナにコピーし、
# 所有権を一度にユーザー app とグループ app に変更します。
COPY --from=build --chown=app:app /app /app

# アプリケーションが上記で pip インストールされた適切な Python パッケージでない場合、
# この部分でアプリケーションをコンテナにコピーする必要があります：
# COPY . /app/whereever-your-entrypoint-finds-it

USER app
WORKDIR /app

# 完全にオプションですが、私は構築した内容を調べるためにこれを好んで使用します。
RUN set -ex \
    && python -V \
    && python -Im site

これ、そんなに悪くない感じがするけど、大したことじゃないの？

本当に大したことはないんです！ただ、仮想環境を /app/.venv に隠しておくよりも、仮想環境が /app/ 自体になって、その中に bin、lib、share がある方が少しだけ使いやすいというだけです^[1]。また、私はスクリプトや Dockerfile で絶対パスを使うのが好きなんですが、/app/.venv/bin/gunicorn よりも /app/bin/gunicorn の方が言いやすいんです。

だから、#5229 を支持します – 自分のワークフローがネイティブにサポートされるまで待てますが、これが実験してみたい人にとって役立つことを願っています！

「パッケージ化されていない」アプリケーションについての注記：Python アプリケーションは、importlib を使ったリソース管理や、scripts フォルダーを無理やり追加するのではなく project.scripts を使った適切な実行スクリプト、src レイアウトの利点、文書化されよく理解された構造のガードレールを享受するために、適切にパッケージ化されるべきだと強く信じています。
Astral が uv 0.4.0 でパッケージ化されていないアプリをサポートした理由は理解できます：大きくなるためには、いい加減なものも含めてすべてのワークフローをカバーする必要がありますし、物事がやっと動くようになったときに新しい概念を学ぶのを嫌がる人がいるのも理解しています – ただ、その抵抗の激しさはちょっと理解できません。はっきり言っておきますが：この機能を削除してほしいとは思っていません – ただ、それが祝われるべきものだとは思いません。
とにかく、何らかの理由でアプリケーションがパッケージ化されていない場合：Dockerfile を調整するためのインラインメモを追加しておきました。簡単に言うと、ビルドステップでアプリケーションをインストールする代わりに、/app を COPY した後にランタイムコンテナにアプリケーションを COPY することになります。/app を上書きしないように注意してください。

P.S. Docker についてもっと助けが必要なら、私の友人 Itamar Turner-Trauring の素晴らしいリソースを参照してください。

P.P.S. Dev Container (訳注^[2]) については聞かないでください – 私は知らないし、知りたくもありません。開発で Docker コンテナを使うことを強制された瞬間、私はヤギの飼育 (訳注^[3]) に切り替えます。

脚注

以前のバージョンの記事では、/app/.venv/bin から /app/bin へのシンボリックリンクを追加することを提案していましたが、それには Python が site を発見する方法に予期しない副作用があったため、削除しました。 ↩︎
訳注: VS Code や GitHub Spaces などにおいて提供されている開発コンテナの機能です: https://code.visualstudio.com/docs/devcontainers/containers ↩︎
訳注: この文脈では、著者が開発環境で Docker を使うことへの不満や抵抗を強調するために、極端な例として「ヤギの飼育」という、全く異なる職業やライフスタイルに切り替えることを冗談めかして言っています。つまり、「開発で Docker を使わなければならないほど嫌なら、むしろプログラミングを辞めて別のことをする」という皮肉やユーモアの表現です。 ↩︎

このスクラップは3ヶ月前にクローズされました