Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Dockerfile krok po kroku: jak stworzyć własny obraz Docker

Techniczny rysunek pokazuje rozłożone warstwy pakietu i arkusz instrukcji.

Kontener uruchomiony z przypadkowo zmienionych plików trudno odtworzyć na drugim serwerze. Dockerfile pozwala zapisać sposób przygotowania aplikacji: obraz bazowy, pliki, użytkownika i polecenie startowe. Z takiego przepisu budujesz obraz, który możesz przetestować i przenieść do kolejnego środowiska.

W tym poradniku przygotujesz małą aplikację HTTP w Pythonie, zbudujesz własny obraz Docker i sprawdzisz działanie kontenera. Przykład służy do nauki budowania obrazów. Wbudowany serwer HTTP Pythona nie jest serwerem produkcyjnym dla publicznego API.

Dockerfile, obraz i kontener to trzy różne rzeczy

Dockerfile jest plikiem instrukcji. Obraz zawiera wynik budowania: system plików oraz konfigurację uruchomienia. Kontener jest uruchomioną instancją obrazu z własnym stanem procesu i zapisywalną warstwą. Zmiana Dockerfile nie aktualizuje już działającego kontenera. Trzeba zbudować nowy obraz i uruchomić z niego nową instancję.

Jeśli te pojęcia nadal się mieszają, zacznij od artykułu Docker: jak działa i do czego służy. Tutaj skupiamy się na przygotowaniu własnego artefaktu, a nie na instalacji silnika.

Schemat łączy plik instrukcji, obraz z warstw i uruchomioną aplikację.
Dockerfile opisuje budowę obrazu, z którego uruchamiasz kontener.

Do wykonania poleceń potrzebujesz działającego Dockera z obsługą kontenerów linuksowych oraz terminala. Polecenia powłoki poniżej zakładają Bash na Linuxie lub WSL. Sprawdź środowisko przez docker version i docker buildx version. Błąd dostępu do gniazda Dockera dotyczy uprawnień środowiska, nie składni Dockerfile. Nie naprawiaj go przez nadawanie gniazdu uprawnień do zapisu wszystkim użytkownikom.

Przygotuj niewielką aplikację

Utwórz pusty katalog i przejdź do niego:

mkdir dockerfile-demo
cd dockerfile-demo

Zapisz plik server.py:

import json
from http.server import BaseHTTPRequestHandler, HTTPServer


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({"status": "ok", "app": "dockerfile-demo"}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


HTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Program odpowiada tym samym JSON-em na każde żądanie GET. Nie ma bazy, uploadów, logowania ani zależności z PyPI. Dzięki temu ewentualny problem łatwiej przypisać do procesu budowania lub sieci. Nasłuch na 0.0.0.0 wewnątrz kontenera pozwala dotrzeć do aplikacji przez jego interfejs sieciowy.

Napisz pierwszy Dockerfile

Obok aplikacji utwórz plik o dokładnej nazwie Dockerfile, bez rozszerzenia:

# syntax=docker/dockerfile:1
FROM python:3.13-slim

WORKDIR /app
RUN groupadd --gid 10001 app \
    && useradd --uid 10001 --gid app --no-create-home app

COPY --chown=10001:10001 server.py /app/server.py

USER 10001:10001
EXPOSE 8000
CMD ["python", "-u", "/app/server.py"]

FROM wybiera środowisko bazowe. W przykładzie jest to linuksowy obraz Pythona z gałęzi 3.13 w wariancie slim. Tag może z czasem wskazywać nowszą zawartość. Gdy potrzebujesz odtwarzalnego wydania, zapisz zweryfikowany digest obrazu bazowego i kontroluj jego aktualizacje. Sama nazwa tagu nie identyfikuje niezmiennego zestawu plików.

WORKDIR ustawia katalog pracy. RUN wykonuje operację podczas budowania, tutaj tworzy konto aplikacji. COPY dodaje konkretny plik z kontekstu budowania. USER określa tożsamość procesu. CMD definiuje domyślne polecenie uruchamiania, a EXPOSE dokumentuje port używany przez aplikację.

Dlaczego RUN nie zastępuje CMD?

Polecenie RUN python server.py próbowałoby uruchomić serwer podczas budowania. Budowa czekałaby na zakończenie procesu. Właściwe miejsce dla długo działającej aplikacji to polecenie startowe kontenera.

Forma CMD jako tablica uruchamia program bez dodatkowej powłoki. Nie interpretuje automatycznie operatorów Bash ani zmiennych zapisanych jako $NAZWA. Opcja -u Pythona ogranicza buforowanie wyjścia, co ułatwia obserwację logów. W bardziej rozbudowanych obrazach ENTRYPOINT może ustalać program, a CMD dostarczać domyślne argumenty.

Po co użytkownik bez roota?

Ta aplikacja nie potrzebuje uprawnień administratora do nasłuchu na porcie 8000. Uruchomienie jej z UID 10001 ogranicza uprawnienia procesu w kontenerze. Nie zastępuje jednak aktualizacji, kontroli mountów ani ochrony hosta. Podłączenie gniazda Dockera lub nadmiernie uprzywilejowane uruchomienie może przekreślić korzyści z samego USER.

Ogranicz kontekst przez .dockerignore

Kropka na końcu docker build ... . wskazuje katalog stanowiący kontekst budowania. Dockerfile może korzystać z dostępnych w nim plików, z uwzględnieniem wykluczeń. To nie musi być cały katalog domowy ani repozytorium zawierające niezwiązane projekty.

Zapisz .dockerignore:

.git
.env
.env.*
*.pem
*.key
__pycache__
*.pyc
.venv

Plik wykluczeń zmniejsza ilość materiału przekazywanego do budowy i ryzyko przypadkowego skopiowania sekretu. W przykładzie i tak kopiujemy tylko server.py, ale jawna lista wykluczeń jest dodatkową ochroną przy późniejszych zmianach. Reguły dopasuj do projektu, aby nie usunąć potrzebnych plików konfiguracyjnych bez sekretów.

Rysunek folderu oddziela pliki aplikacji od klucza i ukrytych danych.
Do kontekstu budowania powinny trafiać tylko potrzebne pliki.

Jeżeli budowa wymaga prywatnego tokenu, nie zapisuj go w ARG, ENV ani w poleceniu, które zostawi go w obrazie. BuildKit udostępnia mounty sekretów na czas konkretnego kroku. Sekret przekazany do procesu budowania nie powinien automatycznie stawać się składnikiem dystrybuowanego obrazu.

Zbuduj obraz i uruchom kontener

W katalogu z trzema plikami wykonaj:

docker build --pull -t dockerfile-demo:1 .
docker run -d --name dockerfile-demo \
  -p 127.0.0.1:18080:8000 \
  dockerfile-demo:1
curl --fail http://127.0.0.1:18080/

Odpowiedź powinna zawierać status: ok i nazwę aplikacji. --pull sprawdza nowszą wersję obrazu bazowego wskazanego tagiem. Nie oznacza całkowitego pominięcia cache pozostałych kroków.

Mapowanie portu ma trzy części: adres hosta, port hosta i port kontenera. Tutaj aplikacja jest dostępna na 127.0.0.1:18080 hosta. Jeżeli wykonujesz polecenia na VPS-ie, adres odnosi się do VPS-a, a nie do Twojego laptopa. Do zdalnego sprawdzenia możesz użyć tunelu SSH. Nie usuwaj adresu loopback tylko po to, żeby obejść problem dostępu.

EXPOSE 8000 nie publikuje portu. Dopiero opcja -p tworzy mapowanie. Z kolei nasłuch wyłącznie na 127.0.0.1 wewnątrz kontenera dotyczyłby jego własnej pętli zwrotnej, przez co zwykłe mapowanie nie dotarłoby do serwera.

Sprawdź proces i logi:

docker ps --filter name=dockerfile-demo
docker logs --tail 20 dockerfile-demo
docker exec dockerfile-demo id
docker inspect --format '{{.Config.User}}' dockerfile-demo

Ostatnie dwie komendy pozwalają potwierdzić rzeczywistą tożsamość procesu i konfigurację użytkownika. Sam fakt udanej budowy nie dowodzi, że aplikacja nasłuchuje na właściwym porcie lub działa z założonymi uprawnieniami.

Cache: kolejność instrukcji wpływa na czas budowania

Docker może ponownie wykorzystać wynik wcześniejszego kroku, jeśli jego wejścia się nie zmieniły. Jeżeli na początku skopiujesz cały projekt, drobna zmiana pliku może unieważnić cache kosztownej instalacji zależności znajdującej się później.

W projekcie korzystającym z requirements.txt typowy układ wygląda tak:

COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r /app/requirements.txt
COPY . /app

To wariant dla aplikacji z zależnościami, nie dodatkowe linie wymagane przez nasz przykład. Oddzielenie pliku zależności od kodu pozwala zachować wynik instalacji, gdy zmienia się tylko aplikacja. Wersje bibliotek powinny być kontrolowane w pliku zależności lub lockfile, a nie pobierane przypadkowo przy każdej budowie.

Stos warstw ma wyróżnioną górną warstwę, którą trzeba przebudować.
Zmiana kodu nie musi unieważniać wcześniej przygotowanych zależności.

--no-cache wymusza ponowne wykonanie kroków, ale nie jest codzienną metodą naprawiania źle ułożonego Dockerfile. Nie zastępuje też --pull. Warto rozróżniać odświeżenie obrazu bazowego od ponownego wykonania własnych instrukcji.

Nowa wersja obrazu nie zmienia starego kontenera

Po zmianie kodu zbuduj drugi tag:

docker build -t dockerfile-demo:2 .
docker stop dockerfile-demo
docker rm dockerfile-demo
docker run -d --name dockerfile-demo \
  -p 127.0.0.1:18080:8000 \
  dockerfile-demo:2

To prosty przykład z przerwą między instancjami. Dla publicznej usługi sposób wdrażania wymaga dodatkowego projektu: testu nowego wydania, kontroli zdrowia i planu powrotu. W aplikacji z danymi zapis w warstwie kontenera nie jest trwałym magazynem. Zewnętrzny wolumen lub baza powinny mieć osobny backup.

Gdy dochodzą kolejne usługi i konfiguracja, wygodniej opisać uruchamianie w Compose. Zobacz jak połączyć kilka kontenerów w Docker Compose. Dockerfile nadal odpowiada za budowę obrazu, a Compose za sposób uruchomienia zestawu.

Najczęstsze problemy

Objaw Co sprawdzić
COPY nie znajduje pliku Katalog kontekstu, wielkość liter i .dockerignore
Kontener od razu kończy pracę Logi, CMD i zakończenie procesu głównego
Port nie odpowiada Adres nasłuchu aplikacji, mapowanie i host, na którym działa Docker
Permission denied UID procesu oraz prawa do plików i podłączonych katalogów
Kod się nie zmienił Czy przebudowano obraz i utworzono nowy kontener z właściwego tagu

Nie modyfikuj działającego kontenera ręcznie jako sposobu tworzenia nowego wydania. Zmiany wykonane przez docker exec mogą zniknąć przy odtworzeniu instancji. Wprowadź poprawkę w źródłach i zbuduj obraz ponownie.

Po ćwiczeniu usuń tylko jego kontener:

docker stop dockerfile-demo
docker rm dockerfile-demo

Nie potrzebujesz globalnego czyszczenia wszystkich obrazów czy wolumenów hosta.

FAQ

Gdzie powinien znajdować się Dockerfile?

Najprościej w katalogu projektu używanym jako kontekst. Możesz wskazać inny plik przez docker build -f sciezka/Dockerfile, ale źródła COPY nadal odnoszą się do wybranego kontekstu.

Czy każda instrukcja tworzy warstwę z plikami?

Nie. Instrukcje zmieniające system plików i instrukcje konfigurujące metadane obrazu pełnią różne role. Nie oceniaj rozmiaru obrazu wyłącznie po liczbie linii Dockerfile.

Kiedy warto użyć multi-stage build?

Gdy do zbudowania aplikacji potrzebujesz kompilatora lub narzędzi, których nie chcesz w obrazie uruchomieniowym. Osobny etap buduje wynik, a końcowy kopiuje tylko potrzebne artefakty. Nasz mały przykład nie wymaga takiego podziału.

Czy obraz slim zawsze będzie najlepszy?

Nie. Mniejszy wariant może wymagać doinstalowania bibliotek systemowych i utrudnić diagnostykę. Dobierz bazę do aplikacji, obsługiwanej architektury oraz sposobu aktualizacji.

Czy mogę zapisać hasło w zmiennej ENV?

Nie zapisuj poufnych wartości w Dockerfile. Taka konfiguracja staje się częścią obrazu. Sekrety uruchomieniowe dostarczaj osobno, a sekrety budowy przez przeznaczony do tego mechanizm BuildKit.

Źródła

Data publikacji: 09.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *