Docker: Node.js

Jak używać i wdrażać aplikację Node.js z Dockerem

👋 Witamy w dokumentacji Stackhero!

Stackhero oferuje gotowe do użycia rozwiązanie Docker cloud CaaS (Containers as a Service), które zapewnia wiele korzyści, w tym:

Łatwe wdrażanie kontenerów do produkcji za pomocą prostego docker-compose up.

Dostosowywana nazwa domeny zabezpieczona HTTPS (na przykład, https://api.twoja-firma.com, https://www.twoja-firma.com, https://backoffice.twoja-firma.com).

Optymalna wydajność i solidne zabezpieczenia dzięki prywatnej i dedykowanej VM.

Bezproblemowe aktualizacje za pomocą jednego kliknięcia.

Oszczędzaj czas i upraszczaj swoje życie: wystarczy 5 minut, aby wypróbować rozwiązanie Docker CaaS cloud hosting Stackhero i wdrożyć swoje kontenery do produkcji!

Ten przewodnik oferuje solidne podstawy do tworzenia aplikacji Node.js i szybkiego oraz łatwego wdrażania jej do produkcji.

Nie jest wymagana wcześniejsza znajomość Dockera. Wszystko jest skonfigurowane, aby zapewnić płynne doświadczenie; wystarczy mieć zainstalowanego Dockera na swoim komputerze.

Dokumentacja jest przeznaczona zarówno dla początkujących, jak i doświadczonych użytkowników, którzy chcą wdrożyć aplikację Node.js przy użyciu nowoczesnych, skalowalnych technologii bez zbędnych komplikacji.

Kluczowe cechy tego rozwiązania obejmują:

💪 Łatwa konfiguracja przy minimalnym wysiłku
🐳 Wykorzystanie Dockera zarówno w środowiskach deweloperskich, jak i produkcyjnych
🔄 Automatyczne przeładowanie Node.js przy zmianach w kodzie za pomocą nodemon
🚀 Wdrożenie do produkcji za pomocą jednej komendy
🔒 Zarządzanie certyfikatami TLS dla bezpiecznego szyfrowania HTTPS
🚧 Wsparcie dla platform staging i preprodukcji
🧱 Modułowa i skalowalna architektura

Pierwsze kroki

Jeśli Docker nie jest jeszcze zainstalowany na Twoim komputerze, możesz go pobrać z oficjalnej strony Dockera. Aby sprawdzić, czy Docker działa poprawnie, otwórz terminal i uruchom docker version. Powinieneś zobaczyć informacje o wersji bez żadnych błędów.

Po zainstalowaniu Dockera, sklonuj następujące repozytorium szablonu:

git clone https://github.com/stackhero-io/nodejsWithDockerGettingStarted/
cd nodejsWithDockerGettingStarted

Następnie uruchom platformę deweloperską, wykonując make development-start lub zobacz wszystkie dostępne komendy za pomocą make help.

Platforma deweloperska

Aby uruchomić platformę deweloperską, wykonaj:

make development-start

Ta komenda buduje obraz Dockera, uruchamia go i wykonuje skrypt dev zdefiniowany w my-app/package.json (co jest równoważne z uruchomieniem npm run dev).

W tym przykładzie tworzona jest prosta API REST przy użyciu Express. Możesz zobaczyć API, przechodząc do http://localhost:5000. Strona powinna wyświetlać "Hello World".

Następnie otwórz plik my-app/src/app.js w preferowanym IDE i zmodyfikuj następującą linię:

res.send('Hello World');

Zmień ją na:

res.send('Updated!');

Zapisz plik. Kod Node.js automatycznie się przeładuje, a odświeżenie http://localhost:5000 odzwierciedli zaktualizowaną odpowiedź API.

Gratulacje - masz teraz w pełni operacyjną platformę deweloperską!

Instalacja pakietów

Jeśli potrzebujesz zainstalować dodatkowe pakiety, możesz uruchomić make development-shell, aby uzyskać dostęp do powłoki kontenera. Wewnątrz użyj NPM z npm install <package> lub Yarn z yarn add <package>, aby zainstalować pożądane pakiety.

Użycie istniejącego projektu Node.js

Jeśli masz istniejący projekt Node.js, który chcesz zintegrować z Dockerem, wykonaj następujące kroki:

Utwórz nowy katalog o nazwie my-app w swoim projekcie.
Przenieś wszystkie pliki projektu do katalogu my-app, z wyjątkiem plików .gitignore i .git.
Skopiuj docker, secrets i Makefile z szablonu do katalogu głównego swojego projektu.
Edytuj plik .gitignore w swoim projekcie i dodaj następujące linie:
```
node_modules/
secrets/*.production
secrets/*.staging
```

Otwarty port

Ten szablon zakłada, że Twoja aplikacja nasłuchuje na porcie 5000. Jeśli wolisz inny port, możesz edytować plik docker/docker-compose.development.yml, a następnie ponownie uruchomić środowisko za pomocą make development-start.

Wybór konkretnej wersji Node.js

Jeśli chcesz określić inną wersję Node.js, wykonaj następujące kroki:

Otwórz plik docker/my-app.dockerfile, który definiuje obraz Dockera dla Twojej aplikacji.
Znajdź pierwszą linię, która brzmi FROM node:<version>-alpine.
Zamień <version> na wybraną wersję Node.js. Zaleca się użycie wersji Long-Term Support (LTS). Możesz sprawdzić najnowszą wersję LTS na stronie Node.js. Na przykład, aby użyć najnowszej wersji LTS (obecnie 22), zaktualizuj linię do FROM node:22-alpine. Jeśli wolisz konkretny numer wersji, możesz użyć czegoś takiego jak FROM node:22.13.0-alpine.
Zapisz swoje zmiany w Dockerfile.

Zmienne środowiskowe

Ustaw zmienne środowiskowe dla platformy deweloperskiej w pliku secrets/my-app.development.

Dla produkcji użyj pliku secrets/my-app.production.

Nie commituj pliku secrets/my-app.production do swojego repozytorium Git! Ten plik zawiera wrażliwe informacje i jest domyślnie ignorowany w .gitignore szablonu, aby zapobiec przypadkowemu udostępnieniu.

Przechowywanie plików lokalnych

Jeśli Twoja aplikacja Node.js musi przechowywać pliki (na przykład przesyłane przez użytkowników), rozważ użycie usługi przechowywania obiektów, takiej jak MinIO. Usługa przechowywania obiektów pomaga Twojej aplikacji skalować się bezproblemowo, jednocześnie zmniejszając potencjalne problemy.

Jeśli wolisz przechowywać pliki lokalnie, upewnij się, że zawsze używasz wolumenu Dockera. Przechowywanie plików bezpośrednio w kontenerze może prowadzić do utraty danych. Ten szablon zapewnia wolumen zamontowany w /persistent do bezpiecznego przechowywania plików.

Nigdy nie przechowuj danych trwałych poza katalogiem /persistent, chyba że utworzyłeś niestandardowe wolumeny i jesteś pewien konfiguracji. Przechowywanie plików poza /persistent spowoduje utratę danych!

Dodanie środowiska staging

Możesz łatwo zmodyfikować ten szablon, aby dodać środowisko staging. Aby to zrobić:

Utwórz kopię docker/docker-compose.production.yml i nazwij ją docker/docker-compose.staging.yml. Ten plik definiuje kontenery i konfigurację dla Twojego środowiska staging.
Utwórz plik secrets secrets/my-app.staging zawierający wszelkie wrażliwe informacje wymagane dla staging, takie jak hasła do bazy danych lub klucze API.
W Makefile znajdź sekcję oznaczoną "Staging platform" i odkomentuj ją.

Na koniec uruchom make help, aby zobaczyć nowe dostępne komendy staging.

Platforma produkcyjna

Jeśli nie masz jeszcze usługi Stackhero for Docker, możesz ją łatwo utworzyć z poziomu swojego dashboardu Stackhero. Zostanie aktywowana w ciągu około 2 minut.

Jeśli jesteś nowy w Stackhero, możesz wypróbować Docker container cloud hosting za darmo przez miesiąc.

Przygotowanie pierwszego wdrożenia do produkcji

Przed wdrożeniem aplikacji do produkcji musisz przygotować kilka plików konfiguracyjnych:

Skopiuj secrets/global.production.example do secrets/global.production.
Edytuj secrets/global.production i zamień <XXXXXX>.stackhero-network.com na nazwę hosta swojej usługi Docker z dashboardu Stackhero.
Skopiuj secrets/my-app.production.example do secrets/my-app.production.
Edytuj secrets/my-app.production i wprowadź swoje dane uwierzytelniające.
Zaktualizuj docker/docker-compose.production.yml, zastępując <XXXXXX>.stackhero-network.com nazwą hosta swojej usługi Docker.

Wdrożenie do produkcji

Wdrożenie do produkcji jest proste: uruchom:

make production-deploy

Ta komenda tworzy kontener Dockera, przesyła dane Twojego projektu i wysyła je do Twojej usługi Docker w produkcji. Otwórz przeglądarkę i przejdź do nazwy hosta swojej usługi Docker (na przykład, https://<XXXXXX>.stackhero-network.com). Powinieneś zobaczyć, jak Twoje API REST odpowiada "Hello World".

Możesz również użyć make production, który wdraża Twoje kontenery i wyświetla logi w czasie rzeczywistym.

Wyświetlanie logów

Aby monitorować swoje środowisko produkcyjne lub rozwiązywać problemy, możesz przeglądać swoje logi za pomocą tych komend:

Aby strumieniować logi na żywo, uruchom: make production-logs-live
Aby pobrać wszystkie zapisane logi, uruchom: make production-logs
Aby pobrać logi z konkretnego dnia (zamień YYYY-MM-DD na żądaną datę), uruchom: make production-logs | grep "YYYY-MM-DD"

Dostosowanie nazw domen

Jeśli chcesz użyć innej nazwy domeny zamiast https://<XXXXXX>.stackhero-network.com, Stackhero for Docker integruje Traefik, aby uprościć zarządzanie domenami. Traefik obsługuje routing HTTP i szyfrowanie TLS (HTTPS) za Ciebie.

Oto kilka przykładów, jak dostosować swoje nazwy domen:

Aby obsługiwać api.my-company.com za pośrednictwem swojego kontenera my-app na porcie 5000 z szyfrowaniem TLS, zaktualizuj plik docker/docker-compose.production.yml, zastępując sekcję labels następującymi wartościami:

    labels:
      - "traefik.enable=true" # Włącz Traefik, aby kierować ruch do tego kontenera
      - "traefik.http.routers.my-app.rule=Host(`api.my-company.com`)" # Zdefiniuj hosta
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt" # Użyj letsencrypt dla certyfikatów TLS
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Określ port 5000

Aby obsługiwać my-company.com za pośrednictwem swojego kontenera my-app na porcie 5000 i przekierować wszystkie żądania z www.my-company.com do my-company.com, zaktualizuj sekcję labels w tym samym pliku następującymi wartościami:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`my-company.com`) || Host(`www.my-company.com`)" # Uwzględnij oba domeny
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Określ port 5000

      # Przekieruj www.my-company.com do my-company.com:
      - "traefik.http.routers.my-app.middlewares=redirect-www"
      - "traefik.http.middlewares.redirect-www.redirectregex.regex=^https://www.my-company.com/(.*)"
      - "traefik.http.middlewares.redirect-www.redirectregex.replacement=https://my-company.com/$${1}"
      - "traefik.http.middlewares.redirect-www.redirectregex.permanent=true"

Nie zapomnij skonfigurować DNS dla my-company.com i www.my-company.com, aby każdy wskazywał jako CNAME na Twoją usługę Docker pod adresem https://<XXXXXX>.stackhero-network.com.