Lidsky řečeno
Dřív se zboží nakládalo na lodě po pytlích a bednách a každý přístav to řešil po svém. Pak přišel standardní kontejner: je jedno, co je uvnitř, jeřáb i loď s ním zacházejí stejně. Docker dělá totéž se softwarem. Do jedné krabice dáš program, Python i všechny knihovny a krabice pojede na tvém notebooku i na serveru.
Konec věty „u mě to funguje“
Program nikdy neběží sám. Potřebuje konkrétní verzi Pythonu, knihovny, systémové balíky a nastavení. Na serveru bývá něco z toho jinak a chyba se objeví až tam. Docker tohle prostředí zabalí s programem. Tři pojmy stačí:
- Image (obraz): neměnná šablona se vším, co program potřebuje. Něco jako zamražený oběd.
- Kontejner: běžící proces spuštěný z image. Z jedné image jich může běžet víc.
- Registr: sklad, odkud se image stahují. Například Docker Hub nebo GitHub Container Registry.
Dockerfile --build--> image --push--> registr
(recept) (šablona) |
pull
v
server: kontejner, kontejnerKontejner není virtuální počítač. Sdílí jádro systému s hostitelem a od ostatních procesů je jen oddělený, proto startuje rychle. Na Windows a macOS běží Docker Desktop uvnitř malého linuxového virtuálu.
Recept se píše do souboru Dockerfile. Dejme tomu, že máš aplikaci z minulé lekce v app/main.py a závislosti v requirements.txt:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]Řádek po řádku: vezmi oficiální malou image s Pythonem, přejdi do složky /app, zkopíruj seznam závislostí, nainstaluj je, zkopíruj kód a nakonec řekni, co se má spustit. Sestavení a spuštění:
docker build -t ukolnicek:dev .
docker run --rm -p 8000:8000 ukolnicek:dev-t dá image jméno. -p 8000:8000 propojí port 8000 tvého počítače s portem 8000 v kontejneru. --rm kontejner po skončení smaže. Další příkazy na každý den:
docker ps # co běží
docker logs -f <kontejner> # výpis programu
docker exec -it <kontejner> sh # shell uvnitř běžícího kontejneru
docker stop <kontejner> # slušné ukončení
docker images # image na tomhle strojiVrstvy a proč záleží na pořadí
Každá instrukce v Dockerfile vytvoří vrstvu. Docker si je pamatuje. Když se instrukce ani její vstupy nezměnily, vezme hotový výsledek z cache. Jakmile se ale jedna vrstva změní, všechny pod ní se sestavují znovu. Následující simulace to ukazuje na dvou Dockerfilech. V obou změníš jeden řádek v main.py.
import hashlib
def build(steps, files, cache):
parent = "python:3.12-slim"
for instruction, inputs in steps:
content = "".join(files[name] for name in inputs)
raw = f"{parent}|{instruction}|{content}"
key = hashlib.sha256(raw.encode()).hexdigest()
print(" CACHED" if key in cache else " BUILD ", instruction)
cache.add(key)
parent = key
ALL_FILES = ["requirements.txt", "main.py"]
bad = [
("COPY . .", ALL_FILES),
("RUN pip install -r requirements.txt", []),
]
good = [
("COPY requirements.txt .", ["requirements.txt"]),
("RUN pip install -r requirements.txt", []),
("COPY main.py .", ["main.py"]),
]
for name, steps in [("špatné pořadí", bad), ("dobré pořadí", good)]:
files = {"requirements.txt": "fastapi==1", "main.py": "print(1)"}
cache = set()
print(name, "- první sestavení")
build(steps, files, cache)
files["main.py"] = "print(2)"
print(name, "- po změně main.py")
build(steps, files, cache)
špatné pořadí - první sestavení BUILD COPY . . BUILD RUN pip install -r requirements.txt špatné pořadí - po změně main.py BUILD COPY . . BUILD RUN pip install -r requirements.txt dobré pořadí - první sestavení BUILD COPY requirements.txt . BUILD RUN pip install -r requirements.txt BUILD COPY main.py . dobré pořadí - po změně main.py CACHED COPY requirements.txt . CACHED RUN pip install -r requirements.txt BUILD COPY main.py .
Ve špatném pořadí se při každé opravě překlepu znovu stahují všechny knihovny. V dobrém se přeinstalují, jen když se změní requirements.txt. Zásada: co se mění zřídka, patří nahoru.
Co se bude sestavovat znovu
Napiš rebuilt_steps(steps, changed). steps je seznam dvojic (instrukce, seznam_souboru), changed množina změněných souborů. Vrať seznam instrukcí, které se sestaví znovu: první krok používající změněný soubor a všechny za ním. Když se nic z toho nezměnilo, vrať prázdný seznam.
def rebuilt_steps(steps, changed):
# doplň
return None
Do image nepatří všechno, co leží ve složce. Soubor .dockerignore funguje jako .gitignore a chrání tě dvakrát: sestavení je rychlejší a COPY nepřibalí tajemství.
.git
.venv
__pycache__/
*.pyc
.env
.env.*
tests/
*.dbProč se COPY requirements.txt . dává před COPY app/ ./app/?
Změna ve vrstvě zneplatní všechny vrstvy pod ní. Instalace knihoven je pomalá a mění se zřídka, takže má být co nejvýš.
Image pro provoz
První Dockerfile funguje, ale běží pod uživatelem root a obsahuje i nástroje potřebné jen při sestavení. Produkční verze má dvě fáze (multi-stage build). V první se staví, do druhé se přenese jen výsledek.
# --- build stage: nothing from here ships except /opt/venv
FROM python:3.12-slim AS build
COPY requirements.lock .
RUN python -m venv /opt/venv \
&& /opt/venv/bin/pip install --no-cache-dir -r requirements.lock
# --- runtime stage
FROM python:3.12-slim
RUN useradd --system --uid 10001 --no-create-home app \
&& mkdir /data && chown app /data
WORKDIR /srv
COPY --from=build /opt/venv /opt/venv
COPY app/ ./app/
ENV PATH="/opt/venv/bin:$PATH" PYTHONUNBUFFERED=1 DB_PATH=/data/tasks.db
USER app
EXPOSE 8000
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
CMD ["python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/health', timeout=2)"]
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]Co tu přibylo:
requirements.lockje seznam přesných verzí včetně závislostí závislostí, takže dnešní a zítřejší sestavení dají totéž. Vyrobí hopip-compilenebouv pip compile, s volbou--generate-hashesi s otisky balíků.USER appspustí program pod obyčejným uživatelem. Když někdo aplikaci prolomí, nezíská v kontejneru práva roota.HEALTHCHECKse pravidelně ptá, jestli aplikace žije. Malá image nemácurl, proto se použije Python, který tam stejně je.urlopenvyhodí výjimku při chybovém stavu a nenulový návratový kód hlásí problém.PYTHONUNBUFFERED=1posílá výpisy hned, takže se vdocker logsneztratí při pádu.
Pod kapotou · PID 1, signály a slušné ukončení
docker stop pošle hlavnímu procesu SIGTERM a po 10 sekundách (mění se přes -t) přijde SIGKILL. Hlavní proces má v kontejneru PID 1 a jádro s ním zachází zvlášť: signál, pro který nemá vlastní obsluhu, se ignoruje. Uvicorn obsluhu má, dokončí rozběhnuté požadavky a skončí.
Proto CMD v exec tvaru (hranaté závorky). Shell tvar CMD uvicorn ... spustí /bin/sh -c a PID 1 může být shell, který signál dítěti nepředá. Výsledek je vždy desetisekundové vypínání a useknuté požadavky. Spouštíš-li aplikaci přes wrapper skript, končí v něm řádkem exec "$@". Když aplikace vytváří podprocesy, přidej docker run --init, ten navíc sbírá zombie procesy.
Škálování: v kontejnerech se obvykle drží jeden proces a přidávají se repliky, protože orchestrátor pak vidí zdraví i paměť každé zvlášť. --workers dává smysl na jediném stroji bez orchestrace. Každý worker je samostatný proces s vlastní pamětí, což u načtených ML modelů rychle bolí.
Bezpečnost image: FROM python:3.12-slim je pohyblivý tag. Pro reprodukovatelnost připni digest (python:3.12-slim@sha256:...) a aktualizace nech na Dependabotu nebo Renovate. Zapnutím --read-only a --cap-drop ALL ubereš útočníkovi další možnosti, jen musíš povolit zápis do /data a /tmp.
Konfigurace a tajemství
Stejná image má běžet na testu i v produkci. Co se liší, tedy adresy, přepínače a hesla, proto nepatří do kódu ani do image, ale do proměnných prostředí. Program si je načte při startu a hned je ověří. Když něco chybí, ať spadne okamžitě, ne až při prvním požadavku o půlnoci.
from dataclasses import dataclass, field
@dataclass(frozen=True)
class Settings:
db_path: str
api_key: str = field(repr=False)
settings = Settings(db_path="/data/tasks.db", api_key="velmi-tajne")
print(settings)
print(settings.api_key == "velmi-tajne")
Settings(db_path='/data/tasks.db') True
field(repr=False) je malá pojistka: když někdo nastavení vypíše do logu, klíč v něm nebude.
Nastavení, které selže včas
Napiš load_settings(env). env je slovník jako os.environ. Funkce vrátí Settings podle pravidel:
APP_ENV: výchozídevelopment, povolenodevelopment,staging,production,PORT: výchozí8000, celé číslo 1 až 65535,API_KEY: vproductionpovinný a neprázdný, jinde výchozí prázdný text.
Při chybě vyhoď ConfigError se všemi problémy najednou: do str(chyba) patří název každé vadné proměnné.
from dataclasses import dataclass, field
class ConfigError(Exception):
pass
@dataclass(frozen=True)
class Settings:
app_env: str
port: int
api_key: str = field(repr=False)
def load_settings(env):
return Settings(env["APP_ENV"], env["PORT"], env["API_KEY"])
Na svém počítači si službu i s úložištěm spustíš přes Docker Compose, který popisuje běh v jednom souboru:
services:
api:
build: .
ports:
- "127.0.0.1:8000:8000"
environment:
APP_ENV: staging
API_KEY: ${API_KEY:?nastav API_KEY v prostředí nebo v .env}
volumes:
- tasks-data:/data
restart: unless-stopped
volumes:
tasks-data:docker compose up --build -d # sestav a spusť na pozadí
docker compose logs -f api
docker compose down # zastav (data ve volume zůstanou)Volume je úložiště mimo kontejner. Kontejner se dá kdykoli zahodit a nahradit, takže cokoli zapsané jinam zmizí s ním.
Když tajemství potřebuješ už při sestavení, třeba token do soukromého indexu balíčků, BuildKit ho připojí jen na dobu jedné instrukce:
RUN --mount=type=secret,id=pip_conf,target=/etc/pip.conf \
pip install --no-cache-dir -r requirements.lockdocker build --secret id=pip_conf,src=$HOME/.config/pip/pip.conf -t ukolnicek:dev .CI: kontrola při každé změně
CI (continuous integration, průběžná integrace) znamená, že při každém pushi a pull requestu nezávislý stroj projde testy a kontroly. CD (continuous delivery) pokračuje dál a hotovou verzi připraví nebo nasadí. Na GitHubu to obstarají GitHub Actions, popsané v YAML souboru v repozitáři:
name: CI
on:
push:
branches: [main]
tags: ["v*.*.*"]
pull_request:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-24.04
strategy:
matrix:
python-version: ["3.12", "3.13"]
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: ${{ matrix.python-version }}
cache: pip
cache-dependency-path: requirements-dev.lock
- run: pip install -r requirements-dev.lock
- run: ruff check .
- run: ruff format --check .
- run: mypy app
- run: pytest -qČti to odshora: při pushi do main, při značce verze a při každém pull requestu spusť úlohu test na čistém Ubuntu, pro dvě verze Pythonu. Když kterýkoli krok skončí chybou, celá úloha selže a GitHub to u pull requestu ukáže. V nastavení větve pak můžeš zakázat sloučení bez zeleného výsledku. Čísla verzí akcí za @ časem stárnou, aktuální jsou na stránce každé akce.
Lidsky řečeno
CI je kontrolor na konci výrobní linky. Nezajímá ho, že u tebe doma výrobek fungoval. Vezme ho, zapne a teprve pak pustí dál. A nikdy nemá špatný den ani nespěchá na oběd.
Druhá úloha po úspěšných testech sestaví image a nahraje ji do registru. Běží jen na push, ne na pull requestu:
image:
needs: test
if: github.event_name == 'push'
runs-on: ubuntu-24.04
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v5
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=sha
type=ref,event=branch
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=maxAkce metadata-action vyrobí značky image podle toho, co se stalo v Gitu. Její logiku si teď napíšeš ve zmenšené podobě.
Značky image
Napiš image_tags(ref, sha). ref je odkaz z Gitu, sha celý hash commitu. Každá vydávaná verze dostane značku sha- a prvních 7 znaků hashe. K tomu:
refs/tags/v1.2.3přidá na začátek1.2.3a1.2, výsledek["1.2.3", "1.2", "sha-abc1234"],refs/heads/mainpřidámain, výsledek["main", "sha-abc1234"],- cokoli jiného (jiné větve, značka jako
v1.2nebov1.2.3-rc1) znamená prázdný seznam: nic se nevydává.
def image_tags(ref, sha):
return ["latest"]
Pod kapotou · dodavatelský řetězec v CI
Workflow běží s přístupem k tajemstvím, takže je to lákavý cíl.
- Připni akce na commit. Tag
@v5může autor nebo útočník přesunout. Přesně to se stalo v březnu 2025 utj-actions/changed-files(CVE-2025-30066), kde přepsané tagy vypisovaly tajemství do logů. Zápisuses: owner/action@<celý SHA> # v5.0.0je odolný a Dependabot ho umí aktualizovat. - Minimální
permissions. Výchozí nastav nacontents: reada přidávej po úlohách. - Injekce přes výrazy.
run: echo "${{ github.event.pull_request.title }}"se dosadí do skriptu před spuštěním, takže titulek PR může být příkaz. Předej ho přesenv:a v shellu použij"$TITLE". pull_request_targetběží s tajemstvími a v kontextu cílového repa. Nikdy v něm nespouštěj kód z forku.- OIDC místo klíčů. S
id-token: writesi workflow vyžádá krátkodobý token od cloudu a dlouhodobé klíče v secrets odpadnou.
Malý detail: ghcr.io vyžaduje malá písmena, ale github.repository je může obsahovat. Proto ruční ghcr.io/${{ github.repository }}:tag selže u repa Acme/App, zatímco metadata-action jméno převede.
Nasazení bez výpadku
Nejjednodušší nasazení na vlastní server jsou dva příkazy. V compose.yaml je místo build: řádek image: ghcr.io/acme/ukolnicek:${TAG}:
export TAG=sha-abc1234
docker compose pull api
docker compose up -d apiNávrat k předchozí verzi je stejný postup se starou značkou. Proto se nasazuje konkrétní značka, a ne latest: ta neříká, co přesně běží, a po ní není kam se vrátit.
Když máš serverů víc, nahrazují se postupně. Nová verze dostane provoz, až když prokáže, že je zdravá. Když neprojde, zbytek zůstává na staré.
def rolling_update(servers, new_version, is_healthy):
previous = list(servers)
for index in range(len(servers)):
servers[index] = new_version
print("nasazeno:", servers)
if not is_healthy(new_version):
servers[:] = previous
print("kontrola selhala, vracím:", servers)
return False
print("hotovo")
return True
good = ["v1", "v1", "v1"]
rolling_update(good, "v2", lambda version: True)
bad = ["v1", "v1", "v1"]
rolling_update(bad, "v3", lambda version: version != "v3")
nasazeno: ['v2', 'v1', 'v1'] nasazeno: ['v2', 'v2', 'v1'] nasazeno: ['v2', 'v2', 'v2'] hotovo nasazeno: ['v3', 'v1', 'v1'] kontrola selhala, vracím: ['v1', 'v1', 'v1']
| Strategie | Jak funguje | Kdy se hodí |
|---|---|---|
| Rolling | nahrazuje repliky po jedné | výchozí volba |
| Blue-green | vedle staré běží celá nová sada, přepne se najednou | rychlý návrat zpět |
| Canary | nová verze dostane malý díl provozu a sledují se chyby | velký provoz, riskantní změny |
Pod kapotou · health checky a migrace
Liveness a readiness jsou dvě otázky. Liveness: „žije proces, nebo ho mám restartovat?“ Readiness: „mám mu posílat provoz?“ Liveness nesmí kontrolovat databázi: při výpadku databáze by orchestrátor restartoval všechny zdravé repliky a výpadek zhoršil. Závislosti patří do readiness. Při vypínání nech readiness nejdřív spadnout a teprve po chvíli přestaň přijímat spojení, jinak load balancer ještě posílá požadavky na proces, který končí.
Migrace databáze se nasazením nejsou atomické. Během rolling update běží stará i nová verze současně nad stejným schématem, takže změna musí být kompatibilní s oběma. Postup expand and contract: přidej nový sloupec jako nepovinný, nasaď kód zapisující do obou, doplň stará data, přepni čtení, a teprve v dalším vydání starý sloupec smaž. Přejmenování sloupce v jednom kroku je nejspolehlivější cesta k výpadku.
Proč do produkce nasazovat značku sha-abc1234, a ne latest?
latest je jen pohyblivé jméno. Dva servery s ním mohou běžet na různých verzích a po chybě nepoznáš, kam se vrátit.
Kam patří heslo k databázi?
Co je v image, přečte každý, kdo ji může stáhnout. Tajemství se k ní připojuje až za běhu.
Vyzkoušej si: Vrstvy a mezipaměť obrazu
Přeskládej příkazy Dockerfile, změň soubor a sleduj, které vrstvy se musí sestavit znovu.