10.2. Hot reload

watcher (родитель)
   │  наблюдает за файлами
   ▼
процесс приложения ──изменение──► убить ──► запустить заново

CMD ["fastapi", "dev", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

ModuleNotFoundError: No module named 'fastapi'

uvicorn app.main:app --reload \
    --reload-dir app \
    --reload-include '*.html' \
    --reload-exclude '*.pyc'

cat /proc/sys/fs/inotify/max_user_watches

OSError: [Errno 28] inotify watch limit reached

services:
  api:
    build:
      context: .
      target: dev
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app/app
          ignore:
            - __pycache__/
        - action: rebuild
          path: ./requirements.txt
        - action: sync+restart
          path: ./config
          target: /app/config

docker compose watch

mkdir -p /tmp/reload/app && cd /tmp/reload

cat > app/__init__.py <<'PY'
"""Приложение для демонстрации hot reload."""
PY

cat > app/main.py <<'PY'
"""Версия правится на host — перезагрузка должна её подхватить."""
import os

from fastapi import FastAPI

VERSION = "1"

app = FastAPI()


@app.get("/")
async def root() -> dict[str, object]:
    return {"version": VERSION, "pid": os.getpid()}
PY

cat > requirements.txt <<'EOF'
fastapi[standard]==0.141.1
EOF

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 PATH="/opt/venv/bin:$PATH"
# Окружение ВНЕ /app: монтирование кода его не скроет
RUN python -m venv /opt/venv
WORKDIR /app

FROM base AS builder
COPY requirements.txt .
RUN pip install -r requirements.txt

FROM builder AS dev
# fastapi dev по умолчанию слушает 127.0.0.1 — в container нужен 0.0.0.0
CMD ["fastapi", "dev", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

FROM base AS runtime
COPY --from=builder /opt/venv /opt/venv
COPY app/ ./app/
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]
EOF

cat > compose.yaml <<'EOF'
name: reload

services:
  api:
    build:
      context: .
      target: dev
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      # Монтируем подкаталог, а не корень: /opt/venv не затрагивается
      - ./app:/app/app
EOF

docker compose up -d --build > /dev/null 2>&1
sleep 8

echo "═══ до правки ═══"
curl -s localhost:8000/ | python3 -m json.tool --compact | sed 's/^/  /'

echo "═══ правим VERSION на host ═══"
sed -i 's/^VERSION = "1"/VERSION = "2-ПРАВКА"/' app/main.py
sleep 4

echo "═══ после правки, без пересборки ═══"
curl -s localhost:8000/ | python3 -m json.tool --compact | sed 's/^/  /'

echo "═══ что сказал watcher ═══"
docker compose logs api --no-log-prefix 2>/dev/null | grep -iE 'reload|change' | tail -3 | sed 's/^/  /'

═══ до правки ═══
  {"version":"1","pid":8}
═══ правим VERSION на host ═══
═══ после правки, без пересборки ═══
  {"version":"2-ПРАВКА","pid":14}
═══ что сказал watcher ═══
  WARNING:  WatchFiles detected changes in 'app/main.py'. Reloading...
  INFO:     Started server process [14]

cd /tmp/reload
echo "═══ добавляем зависимость в requirements.txt ═══"
echo "httpx==0.28.1" >> requirements.txt

cat > app/main.py <<'PY'
"""Версия с новой зависимостью."""
import os

from fastapi import FastAPI

VERSION = "3"

app = FastAPI()


@app.get("/")
async def root() -> dict[str, object]:
    try:
        import httpx
        dep = f"httpx {httpx.__version__}"
    except ModuleNotFoundError as exc:
        dep = f"ОШИБКА: {exc}"
    return {"version": VERSION, "pid": os.getpid(), "dependency": dep}
PY

sleep 4
echo "═══ перезагрузка подхватила код, но не зависимость ═══"
curl -s localhost:8000/ | python3 -m json.tool --compact | sed 's/^/  /'

echo "═══ после пересборки ═══"
docker compose up -d --build > /dev/null 2>&1
sleep 8
curl -s localhost:8000/ | python3 -m json.tool --compact | sed 's/^/  /'

═══ добавляем зависимость в requirements.txt ═══
═══ перезагрузка подхватила код, но не зависимость ═══
  {"version":"3","pid":21,"dependency":"ОШИБКА: No module named 'httpx'"}
═══ после пересборки ═══
  {"version":"3","pid":8,"dependency":"httpx 0.28.1"}

cd /tmp/reload
echo "═══ вариант с монтированием всего каталога ═══"
cat > compose.bad.yaml <<'EOF'
name: reload-bad

services:
  api:
    build:
      context: .
      target: dev
    volumes:
      - .:/app          # монтируем ВЕСЬ каталог
    command: ["python", "-c", "import fastapi; print('  fastapi найден')"]
EOF

docker compose -f compose.bad.yaml run --rm -T api 2>&1 | tail -2 | sed 's/^/  /'

echo "═══ вариант с монтированием подкаталога ═══"
cat > compose.good.yaml <<'EOF'
name: reload-good

services:
  api:
    build:
      context: .
      target: dev
    volumes:
      - ./app:/app/app     # монтируем ТОЛЬКО код
    command: ["python", "-c", "import fastapi; print('  fastapi найден')"]
EOF

docker compose -f compose.good.yaml run --rm -T api 2>&1 | tail -1 | sed 's/^/  /'
docker compose -f compose.bad.yaml down > /dev/null 2>&1
docker compose -f compose.good.yaml down > /dev/null 2>&1

═══ вариант с монтированием всего каталога ═══
    fastapi найден
═══ вариант с монтированием подкаталога ═══
    fastapi найден

cd /tmp/reload
cat > Dockerfile.venv-inside <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 PATH="/app/.venv/bin:$PATH"
WORKDIR /app
COPY requirements.txt .
RUN python -m venv /app/.venv && /app/.venv/bin/pip install -q fastapi==0.141.1
COPY app/ ./app/
CMD ["python", "-c", "import fastapi; print('fastapi найден')"]
EOF

docker build -q -f Dockerfile.venv-inside -t reload:venv-inside . > /dev/null
echo "═══ venv в /app/.venv, без монтирования ═══"
docker run --rm reload:venv-inside 2>&1 | tail -1 | sed 's/^/  /'
echo "═══ то же, но с монтированием всего каталога ═══"
docker run --rm -v "$PWD:/app" reload:venv-inside 2>&1 | tail -1 | sed 's/^/  /'
echo "═══ и с anonymous volume поверх .venv ═══"
docker run --rm -v "$PWD:/app" -v /app/.venv reload:venv-inside 2>&1 | tail -1 | sed 's/^/  /'
docker rmi -f reload:venv-inside > /dev/null

═══ venv в /app/.venv, без монтирования ═══
  fastapi найден
═══ то же, но с монтированием всего каталога ═══
  /usr/local/bin/python: No module named fastapi
═══ и с anonymous volume поверх .venv ═══
  fastapi найден

cd /tmp/reload
echo "═══ лимит inotify на host ═══"
printf '  max_user_watches:   %s\n' "$(cat /proc/sys/fs/inotify/max_user_watches)"
printf '  max_user_instances: %s\n' "$(cat /proc/sys/fs/inotify/max_user_instances)"

echo "═══ сколько файлов наблюдалось бы без ограничения ═══"
mkdir -p noise
for i in $(seq 1 200); do
    mkdir -p "noise/dir-$i" && touch "noise/dir-$i/file.txt"
done
printf '  каталогов в проекте: %s\n' "$(find . -type d | wc -l)"

echo "═══ ограничиваем область наблюдения ═══"
cat > compose.watchdir.yaml <<'EOF'
name: reload-wd

services:
  api:
    build:
      context: .
      target: dev
    ports:
      - "127.0.0.1:8001:8000"
    volumes:
      - .:/app
      - /app/.venv
    command:
      - uvicorn
      - app.main:app
      - --host
      - 0.0.0.0
      - --reload
      - --reload-dir
      - app                    # только каталог app, не весь проект
EOF

docker compose -f compose.watchdir.yaml up -d --build > /dev/null 2>&1
sleep 8
docker compose -f compose.watchdir.yaml logs api --no-log-prefix 2>/dev/null \
    | grep -iE 'reload|watching' | head -2 | sed 's/^/  /'

echo "═══ изменение вне области наблюдения ═══"
touch noise/dir-1/file.txt
sleep 3
n1="$(docker compose -f compose.watchdir.yaml logs api --no-log-prefix 2>/dev/null | grep -c 'Reloading' || true)"
printf '  перезагрузок после правки в noise/: %s\n' "$n1"

echo "═══ изменение внутри области ═══"
sed -i 's/^VERSION = "3"/VERSION = "4"/' app/main.py
sleep 4
n2="$(docker compose -f compose.watchdir.yaml logs api --no-log-prefix 2>/dev/null | grep -c 'Reloading' || true)"
printf '  перезагрузок после правки в app/:   %s\n' "$n2"

docker compose -f compose.watchdir.yaml down > /dev/null 2>&1
rm -rf noise

═══ лимит inotify на host ═══
  max_user_watches:   65536
  max_user_instances: 128
═══ сколько файлов наблюдалось бы без ограничения ═══
  каталогов в проекте: 204
═══ ограничиваем область наблюдения ═══
  INFO:     Will watch for changes in these directories: ['/app/app']
  INFO:     Started reloader process [1] using WatchFiles
═══ изменение вне области наблюдения ═══
  перезагрузок после правки в noise/: 0
═══ изменение внутри области ═══
  перезагрузок после правки в app/:   1

cd /tmp/reload
cat > compose.watch.yaml <<'EOF'
name: reload-watch

services:
  api:
    build:
      context: .
      target: dev
    ports:
      - "127.0.0.1:8002:8000"
    # Никакого bind mount: файлы синхронизируются
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app/app
          ignore:
            - __pycache__/
        # Изменение зависимостей пересобирает образ автоматически
        - action: rebuild
          path: ./requirements.txt
EOF

echo "═══ образ должен содержать код: bind mount отсутствует ═══"
cat > Dockerfile.watch <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 PATH="/opt/venv/bin:$PATH"
RUN python -m venv /opt/venv
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY app/ ./app/
CMD ["fastapi", "dev", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]
EOF
sed -i 's|      context: .\n      target: dev|      context: .|' compose.watch.yaml
python3 - <<'PY'
import pathlib
p = pathlib.Path("compose.watch.yaml")
t = p.read_text().replace("      context: .\n      target: dev\n",
                          "      context: .\n      dockerfile: Dockerfile.watch\n")
p.write_text(t)
PY

docker compose -f compose.watch.yaml up -d --build > /dev/null 2>&1
sleep 8
printf '  до правки: %s\n' "$(curl -s localhost:8002/ | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])')"

echo "═══ запускаем watch в фоне ═══"
docker compose -f compose.watch.yaml watch > /tmp/reload/watch.log 2>&1 &
watch_pid=$!
sleep 5

sed -i 's/^VERSION = "4"/VERSION = "5-СИНХРОНИЗИРОВАНО"/' app/main.py
sleep 6
printf '  после правки: %s\n' "$(curl -s localhost:8002/ | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])')"
grep -iE 'sync|rebuild' /tmp/reload/watch.log | head -3 | sed 's/^/  /'

kill $watch_pid 2>/dev/null
wait $watch_pid 2>/dev/null
docker compose -f compose.watch.yaml down > /dev/null 2>&1

  до правки: 4
═══ запускаем watch в фоне ═══
  после правки: 5-СИНХРОНИЗИРОВАНО
  Syncing service "api" after changes were detected: app/main.py

cd /tmp/reload
docker compose -f compose.watch.yaml up -d > /dev/null 2>&1
sleep 6
docker compose -f compose.watch.yaml exec -T api sh -c 'echo "создано в container" > /app/app/generated.txt'
printf '  в container: %s\n' \
    "$(docker compose -f compose.watch.yaml exec -T api ls /app/app/generated.txt 2>/dev/null || echo 'нет')"
printf '  на host:     %s\n' \
    "$(ls app/generated.txt 2>/dev/null || echo 'нет — файлы не возвращаются')"
docker compose -f compose.watch.yaml down > /dev/null 2>&1

  в container: /app/app/generated.txt
  на host:     нет — файлы не возвращаются

cd /tmp/reload && docker compose down > /dev/null 2>&1
cd /tmp && rm -rf /tmp/reload

mkdir -p /tmp/hr/app && cd /tmp/hr
printf 'VERSION = "1"\n' > app/v.py
cat > compose.yaml <<'EOF'
name: hr
services:
  a:
    image: python:3.13-slim
    working_dir: /app
    volumes:
      - ./app:/app/app
    command: ["sh", "-c", "while true; do python -c 'import sys; sys.path.insert(0,\"/app\"); from app.v import VERSION; print(VERSION)'; sleep 2; done"]
EOF
docker compose up -d
sleep 3
sed -i 's/"1"/"2"/' app/v.py
sleep 4
docker compose logs a --no-log-prefix | tail -3
docker compose down
cd /tmp && rm -rf /tmp/hr