Obraz Docker z .NET nie startuje

Obraz Docker z .NET niestartujący wskazuje na niekompatybilność wersji runtime kontenera z platformą hosta lub błędnie skonfigurowany Dockerfile.

Obraz Docker z .NET nie startuje – czym jest ten problem

Komunikat „Obraz Docker z .NET nie startuje” oznacza, że przygotowany obraz kontenera nie przechodzi poprawnie od etapu uruchamiania do pracy aplikacji. Sam obraz może zostać pobrany i zapisany lokalnie, a mimo to proces końcowy zakończy się błędem. W praktyce problem może pojawić się podczas odczytu polecenia ENTRYPOINT, ładowania bibliotek, inicjalizacji środowiska .NET albo otwierania portu aplikacji. Nie zawsze oznacza to uszkodzenie samego Dockera. Często przyczyną jest różnica między tym, co zbudowano w obrazie, a tym, czego wymaga aplikacja w chwili startu.

Obraz zawiera warstwy systemowe, środowisko uruchomieniowe, pliki aplikacji i instrukcje określające sposób rozpoczęcia procesu. Jeżeli jedna z tych części nie pasuje do pozostałych, kontener może zakończyć działanie natychmiast po uruchomieniu. Znaczenie ma między innymi wersja platformy .NET, typ projektu, sposób publikacji, architektura procesora oraz system używany przez hosta. Inny zestaw zależności będzie potrzebny aplikacji skompilowanej dla .NET 6, a inny aplikacji wymagającej .NET 8. Należy też odróżnić obraz aplikacyjny od kontenera: obraz jest wzorcem, natomiast kontener jest uruchomioną instancją tego wzorca.

Obraz Docker z .NET nie startuje – kontekst techniczny i porównanie podejść

W rozwiązaniach opartych na .NET spotyka się zwykle obrazy typu runtime, aspnet oraz sdk. Obraz SDK zawiera narzędzia potrzebne do kompilowania i publikowania projektu, natomiast wariant runtime jest przeznaczony do wykonywania gotowej aplikacji. W przypadku aplikacji webowej używa się zazwyczaj obrazu z ASP.NET Core, a dla programu konsolowego wystarcza odpowiednie środowisko .NET Runtime. Wybór niewłaściwego wariantu może spowodować brak pliku wykonywalnego, brak wymaganej biblioteki albo nieprawidłowe działanie polecenia startowego.

Warto porównać dwa sposoby budowania obrazu. W konstrukcji wieloetapowej pierwszy etap korzysta z obrazu SDK i wykonuje przywracanie pakietów, kompilację oraz publikację. Drugi etap otrzymuje wyłącznie wynik publikacji i korzysta z mniejszego obrazu uruchomieniowego. Takie podejście ogranicza liczbę zbędnych plików, ale wymaga poprawnego skopiowania katalogu wynikowego. W konstrukcji jednoetapowej wszystkie czynności wykonywane są w jednym obrazie, co upraszcza konfigurację, jednak utrudnia rozdzielenie narzędzi budowania od środowiska potrzebnego podczas pracy.

Podczas analizy należy zestawić deklarację TargetFramework w pliku projektu z tagiem obrazu bazowego w Dockerfile. Trzeba również sprawdzić, czy aplikacja została opublikowana jako zależna od środowiska, czy jako samodzielna. Publikacja zależna od środowiska wymaga obecności właściwego runtime w obrazie. Publikacja samodzielna może zawierać potrzebne składniki, ale nadal musi odpowiadać architekturze, na której kontener jest uruchamiany. Różnica pomiędzy linux-x64, linux-arm64 i innymi wariantami może doprowadzić do błędu wykonania nawet wtedy, gdy proces budowania zakończył się bez ostrzeżeń.

Obraz Docker z .NET nie startuje – typowe problemy i źródła błędów

Jednym z częstszych powodów jest użycie niezgodnej wersji środowiska. Aplikacja może wymagać konkretnego runtime, podczas gdy Dockerfile odwołuje się do innego tagu. Podobny efekt pojawia się po zmianie wersji pakietów bez ponownego sprawdzenia obrazu bazowego. Warto odczytać pełny komunikat z polecenia docker logs, ponieważ sama informacja o zatrzymaniu kontenera jest zbyt ogólna. Komunikaty o braku pliku, nieznanym poleceniu, nieobsługiwanej wersji frameworka lub błędzie ładowania biblioteki wskazują na różne obszary konfiguracji.

Problematyczne bywa także polecenie ENTRYPOINT albo CMD. Nazwa pliku wynikowego może nie odpowiadać nazwie użytej w Dockerfile, a ścieżka robocza może być inna niż zakładano. Jeżeli plik nie ma odpowiednich uprawnień albo zapisano go z niewłaściwym formatem końca linii, skrypt startowy może zakończyć się przed uruchomieniem .NET. Należy sprawdzić zawartość obrazu za pomocą powłoki uruchomionej tymczasowo, a także zweryfikować wynik poleceń docker image inspect i docker container inspect.

Kolejną grupę przyczyn stanowią pliki pomijane przez .dockerignore. Wykluczenie katalogu z publikacją, konfiguracji lub certyfikatów może sprawić, że obraz zbuduje się poprawnie, lecz aplikacja nie znajdzie zasobu podczas startu. Błędna kolejność instrukcji COPY, niepoprawny katalog roboczy albo pozostawienie starych warstw w pamięci podręcznej również może utrudnić rozpoznanie przyczyny. Dla testu można wykonać budowanie bez cache, a następnie uruchomić kontener z wyraźnie określonymi zmiennymi środowiskowymi.

Nie należy pomijać ustawień portu. Aplikacja może nasłuchiwać wyłącznie na localhost wewnątrz kontenera, podczas gdy oczekiwane jest nasłuchiwanie na wszystkich interfejsach. W takim przypadku proces może działać, lecz usługa będzie niedostępna z zewnątrz. Trzeba rozdzielić błąd rzeczywistego zakończenia procesu od błędu połączenia z aplikacją. Pomocne jest sprawdzenie statusu kontenera, mapowania portów, zmiennych konfiguracji oraz komunikatów aplikacji.

Obraz Docker z .NET nie startuje – praktyczne wskazówki diagnostyczne

Diagnostykę najlepiej prowadzić od informacji najbardziej podstawowych. Najpierw należy ustalić, czy problem występuje podczas budowania obrazu, czy dopiero po wykonaniu polecenia uruchamiającego kontener. Następnie warto zapisać dokładny tag obrazu bazowego, wersję SDK używaną podczas publikacji i wynik polecenia pokazującego architekturę środowiska. Ułatwia to wykrycie sytuacji, w której obraz został utworzony na jednej platformie, a uruchamiany jest na innej.

• Należy porównać wersję określoną w pliku projektu z wersją runtime dostępną w obrazie.
• Trzeba sprawdzić, czy plik wskazany w ENTRYPOINT rzeczywiście znajduje się w kontenerze.
• Warto zweryfikować katalog roboczy, ścieżki kopiowania oraz zawartość pliku .dockerignore.
• Należy odczytać logi kontenera bez skracania komunikatów i zanotować kod zakończenia procesu.
• Trzeba sprawdzić zmienne środowiskowe, wymagane sekrety, połączenia sieciowe i mapowanie portów.
• W razie wątpliwości warto wykonać czyste budowanie obrazu, aby wykluczyć nieaktualną pamięć podręczną.

Przydatne jest również rozdzielenie problemu na etap publikacji i etap uruchomienia. Wynik publikacji można uruchomić poza kontenerem, a następnie sprawdzić ten sam katalog w obrazie. Jeżeli aplikacja działa lokalnie, ale nie działa w kontenerze, należy skoncentrować się na runtime, ścieżkach, uprawnieniach, certyfikatach i zmiennych środowiskowych. Jeżeli nie działa także poza Dockerem, przyczyny należy szukać w projekcie, zależnościach lub konfiguracji aplikacji.

Bezpieczniej jest stosować przypięte, świadomie wybrane wersje obrazów zamiast pozostawiać nieokreślone tagi. Zmniejsza to ryzyko nieoczekiwanej zmiany środowiska przy kolejnym budowaniu. Po modyfikacji Dockerfile należy ponownie sprawdzić logi, kod zakończenia i dostępność usługi. Sam fakt pomyślnego utworzenia obrazu nie potwierdza jeszcze, że aplikacja będzie działała po uruchomieniu.

Kiedy zgłosić obraz Docker z .NET nie startuje do serwisu

Zgłoszenie do serwisu jest uzasadnione, gdy kontener kończy pracę bez czytelnego komunikatu, problem powtarza się po zmianie obrazu bazowego, aplikacja traci pliki podczas budowania albo konieczne jest odtworzenie działającej konfiguracji na innym komputerze. Warto przekazać Dockerfile, plik projektu, pełny log uruchomienia, wynik inspekcji obrazu oraz informację o systemie i architekturze sprzętu. Nie powinno się przekazywać haseł ani kluczy dostępowych; przed udostępnieniem konfiguracji należy zastąpić je bezpiecznymi symbolami.

Warszawskie Pogotowie Komputerowe 24/7 zajmuje się diagnostyką problemów z komputerami i środowiskami używanymi do uruchamiania aplikacji. Przy zgłoszeniu warto jasno opisać, czy obraz nie buduje się, czy kontener uruchamia się i natychmiast zatrzymuje, czy też aplikacja działa, lecz pozostaje niedostępna przez sieć. Takie rozróżnienie skraca analizę i pozwala skupić się na właściwym fragmencie konfiguracji. Po sprawdzeniu można uporządkować Dockerfile, dopasować wersje .NET, poprawić ścieżki publikacji oraz przygotować procedurę ponownego testu.

Nie należy odkładać diagnostyki, gdy kontenery są częścią procesu tworzenia kopii, obsługi plików lub innych zadań wymagających ciągłości działania. Powtarzające się restarty, brak dostępu do danych albo samoczynne zamykanie procesu mogą wskazywać na błąd konfiguracji, niezgodność zależności lub problem z zasobami hosta. Dokładne logi i zachowanie kontenera po czystym uruchomieniu pozwalają odróżnić błąd obrazu od problemu z aplikacją, siecią albo systemem, na którym Docker pracuje.