.NET nie działa w środowisku Docker

W kontenerach Docker .NET wymaga odpowiedniego obrazu bazowego zgodnego z wersją aplikacji (runtime, aspnet czy sdk) — błędy zwykle wynikają z niedopasowania wersji obrazu do wymagań aplikacji.

.NET nie działa w środowisku Docker – na czym polega problem

Komunikat „.NET nie działa w środowisku Docker” zwykle oznacza, że aplikacja uruchamiana w kontenerze nie znajduje wymaganych bibliotek, nie może załadować właściwego środowiska uruchomieniowego albo kończy działanie podczas startu. Sam Docker odpowiada za izolację procesu i dostarczenie mu systemu plików, zmiennych środowiskowych oraz zależności określonych w obrazie. Nie gwarantuje jednak automatycznej zgodności pomiędzy projektem .NET a wybranym obrazem kontenera.

Znaczenie ma rozróżnienie pomiędzy obrazem przeznaczonym do budowania aplikacji a obrazem służącym wyłącznie do jej uruchamiania. Obraz SDK zawiera narzędzia potrzebne do kompilacji, przywracania pakietów i publikowania projektu. Obraz runtime albo ASP.NET Core Runtime jest lżejszy i powinien zawierać składniki niezbędne do pracy gotowego programu. Jeżeli w końcowym etapie używany jest obraz pozbawiony wymaganego środowiska, aplikacja może zostać poprawnie zbudowana, lecz nie uruchomi się po utworzeniu kontenera.

Problem może dotyczyć zarówno aplikacji korzystającej z platformy .NET, jak i programu opartego na starszej rodzinie .NET Framework. Te środowiska nie są wymienne. Projekt przeznaczony dla klasycznego .NET Framework wymaga zwykle odpowiedniej platformy systemowej, podczas gdy współczesny .NET został zaprojektowany z myślą o pracy między różnymi systemami. Z tego powodu próba uruchomienia projektu w niepasującym typie obrazu może prowadzić do błędów już na etapie budowania lub dopiero przy starcie procesu.

Jak Docker i .NET zależą od siebie

Obraz kontenera można porównać do przygotowanego środowiska pracy, w którym określono system bazowy, dostępne biblioteki, użytkownika procesu, katalog roboczy oraz polecenie uruchamiające aplikację. W przypadku .NET istotne jest, aby te elementy odpowiadały projektowi znajdującemu się w repozytorium. W pliku projektu określana jest wersja docelowego frameworka, a w pliku Dockerfile wybierany jest obraz bazowy. Jeżeli oba ustawienia wskazują różne generacje platformy, pojawia się ryzyko braku zgodności.

Typowy proces składa się z kilku etapów. Najpierw przywracane są zależności projektu, następnie wykonywana jest kompilacja, a na końcu publikowane są pliki przeznaczone do uruchomienia. Przy konstrukcji wieloetapowego Dockerfile etap budowania może korzystać z obrazu SDK, natomiast etap końcowy powinien otrzymać odpowiedni obraz uruchomieniowy. Błąd w kopiowaniu plików pomiędzy etapami, pominięcie publikacji albo wskazanie nieprawidłowego katalogu roboczego może sprawić, że w kontenerze zabraknie pliku wykonywalnego lub bibliotek wymaganych podczas startu.

Warto również sprawdzić sposób publikowania aplikacji. Przy publikacji zależnej od środowiska uruchomieniowego kontener musi zawierać zgodną wersję runtime. Przy publikacji samowystarczalnej część komponentów jest dołączana do wyniku, ale nadal znaczenie ma zgodność z systemem bazowym i architekturą obrazu. Nie można zakładać, że obraz przygotowany dla jednego typu procesora uruchomi się bez zmian w każdym innym środowisku.

Na działanie aplikacji wpływają także ustawienia przekazywane podczas uruchamiania kontenera. Należy zweryfikować zmienne środowiskowe, port nasłuchu, ścieżki do plików konfiguracyjnych, uprawnienia użytkownika oraz sposób montowania woluminów. Jeżeli konfiguracja została przygotowana dla komputera gospodarza, a następnie bez zmian przeniesiona do kontenera, odwołania do lokalnych katalogów lub usług mogą przestać działać.

Najczęstsze błędy przy uruchamianiu aplikacji .NET w kontenerze

Jednym z częstszych powodów jest komunikat wskazujący na brak odpowiedniej wersji frameworka. Może to oznaczać, że aplikacja oczekuje konkretnego runtime, a obraz zawiera inną wersję lub wyłącznie narzędzia SDK. Podobny skutek daje użycie obrazu ASP.NET Core dla programu, który wymaga pełnego środowiska .NET, albo odwrotnie. Weryfikacja powinna obejmować wersję określoną w pliku projektu, wersję obrazu bazowego oraz wynik polecenia publikowania.

Inna grupa problemów wynika z nieprawidłowego polecenia startowego. Kontener może zostać utworzony, ale natychmiast się zatrzymać, jeśli wskazano nieistniejący plik DLL, zastosowano błędną nazwę projektu lub pominięto parametr wymagany przez aplikację. Należy sprawdzić logi kontenera, status procesu oraz rzeczywistą zawartość katalogu wynikowego. Sam fakt, że obraz został zbudowany bez błędów, nie oznacza jeszcze, że proces uruchomi się poprawnie.

Problemy mogą pojawić się przy kopiowaniu plików z niewłaściwego miejsca. Plik .dockerignore może wykluczyć zasoby potrzebne do budowania, a polecenia COPY mogą odwoływać się do katalogu, który nie znajduje się w dozwolonym kontekście budowania. W rezultacie obraz może powstać z niepełną aplikacją. Niekiedy przyczyną jest również różnica wielkości liter w nazwach plików, szczególnie gdy projekt był tworzony na systemie, który traktuje takie nazwy mniej rygorystycznie niż system używany wewnątrz kontenera.

Warto zwrócić uwagę na certyfikaty, połączenia sieciowe i zależności natywne. Aplikacja .NET może wymagać certyfikatu urzędu, dodatkowego pakietu systemowego albo dostępu do określonej usługi. Brak takiego elementu może zostać zgłoszony jako błąd połączenia, błąd ładowania biblioteki lub nieudana inicjalizacja komponentu. Nie należy rozwiązywać takich objawów przez przypadkowe instalowanie pakietów. Najpierw powinno zostać ustalone, która zależność jest rzeczywiście wymagana przez aplikację.

Nieprawidłowa konfiguracja portu jest kolejnym częstym źródłem nieporozumień. Aplikacja może działać wewnątrz kontenera, lecz pozostawać niedostępna z zewnątrz, jeśli proces nasłuchuje wyłącznie na lokalnym interfejsie albo port kontenera nie został prawidłowo powiązany z portem hosta. W takiej sytuacji pomocne jest rozdzielenie dwóch kwestii: sprawdzenia, czy proces .NET działa, oraz sprawdzenia, czy ruch dociera do właściwego miejsca.

Kiedy najlepiej umówić wizytę serwisową - .NET nie działa w środowisku Docker

Zgłoszenie do serwisu jest uzasadnione, gdy aplikacja uruchamia się poza Dockerem, lecz w kontenerze nie działa mimo poprawnie wykonanej kompilacji, albo gdy problem pojawia się po aktualizacji środowiska, systemu lub narzędzi programistycznych. W pierwszej kolejności powinno zostać zabezpieczone środowisko robocze i zebrane komunikaty z logów. Przydatne są także pliki Dockerfile, konfiguracja uruchomieniowa, fragment pliku projektu oraz informacja, na którym etapie proces się zatrzymuje.

W Warszawskim Pogotowiu Komputerowym 24/7 można zlecić sprawdzenie komputera, na którym występują problemy z Dockerem i aplikacjami .NET, wraz z analizą podstawowej konfiguracji systemu oraz środowiska uruchomieniowego. Naprawy z reguły są realizowane w ciągu do 3 dni roboczych, zależnie od zakresu diagnostyki i dostępności niezbędnych informacji.

Przed przekazaniem sprzętu warto przygotować kopię projektu, pliki konfiguracyjne pozbawione haseł, opis ostatniej działającej konfiguracji oraz pełny komunikat błędu. Nie powinno się przekazywać kluczy dostępowych ani danych uwierzytelniających zapisanych w zmiennych środowiskowych. Tak przygotowane materiały ułatwiają rozdzielenie problemu sprzętowego od błędu konfiguracji kontenera, niezgodności wersji .NET lub niewłaściwego sposobu uruchamiania aplikacji.

Jeżeli kontener zatrzymuje się natychmiast, komputer działa niestabilnie, występują problemy z pamięcią masową albo system nie pozwala na prawidłową instalację i uruchomienie narzędzi, potrzebna może być szersza kontrola urządzenia. W takiej sytuacji analizuje się kolejno stan systemu, dostępne zasoby, konfigurację wirtualizacji wymaganej przez Docker oraz logi aplikacji. Pozwala to ustalić, czy źródłem niepowodzenia jest sam projekt .NET, obraz kontenera, konfiguracja uruchomieniowa czy środowisko komputera.