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.

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.

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.

--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
- Dockerfile reference, Docker Docs - instrukcje i konfiguracja obrazu.
- Build context, Docker Docs - kontekst i wykluczenia.
- Optimize cache usage, Docker Docs - kolejność kroków i cache.
- Building best practices, Docker Docs - baza, użytkownik i powtarzalność.
- Build secrets, Docker Docs - sekrety podczas budowania.
- Port publishing and mapping, Docker Docs - publikowanie portów.
- http.server, Python Software Foundation - działanie i ograniczenia serwera demonstracyjnego.
Data publikacji: 09.10.2026.

Dyskusja