NodeJS develompent v Dockeru

Pokud se motáte okolo webového vývoje (frontendy, api a pod...) a používáte JavaScript (respektive NodeJS), tak jste se určitě už setkali s následujícím problémem. Různé projekty jsou napsány pod různými verzemi programovacího jazyka a ne vždy je možné vše upgradovat na poslední verzi.

• Můžete používat knihovny, které ještě nejsou upraveny pro novou verzi.
• Starší verze frameworku s poslední verzí jazyka nefunguje.
• Zpětná nekompatibilita.
• Prostě nejsou peníze nebo není čas zabývat se přechodem a přepisem aplikace na poslední verzi.

Důvodů může být milión, ale klíčové je to, že pokud jste to vy co musí do těchto projektů zasahovat, tak musíte provozovat více verzí jazyka.

Pokud se potýkáte s tímto problémem, tak nehledě na jakém operačním systému se nacházíte, budou scénáře podobné.

Scénář 1 - Jedna verze v systému

Tohle je pro popisovaný problém asi nejhorší situace. Máte v systému jednu verzi jazyka. Všechny projekty, na kterých pracujete, musejí běžet pod touhle verzí. Zpravidla to skončí tak, že verze jazyka bude taková, jakou potřebuje ten nejstarší (legacy) projekt. Může vás to zablokovat na tolik, že nebudete moci použít poslední verze frameworků nebo poslední funkcionalitu, protože nebudou tak starou verzi jazyka podporovat.

Scénář 2 - NVM

Node Version Manager (NVM) je utilita, která vám umožní provozovat více verzí jazyka na jednom stroji a přepínat mezi nimi. Existuje jak pro Linux, MacOs, tak i pro Windows. Ve chvíli kdy se přepínáte mezi verzemi a používáte současně jednu, je to přímočaré a elegantní řešení. Ve chvíli, kdy potřebujete mít několik projektů puštěných naráz, pod různými verzemi jazyka, už samozřejmě vyžaduje určitou míru konfigurace. Ale zrovna k tomuto scénáři nemám moc co říct, protože jsem provozoval jen tu nejprimitivnější formu čistě přepínání mezi verzemi. Každopádně se jedná o funkční řešení.

Scénář 3 - Vagrant

Vagrant od HashiCorp používá pro oddělení prostředí virtualizaci. Vytvoříte předpis, který nakonfiguruje virtuální stroj, ve kterém následně aplikaci vyvíjíte. Je možné nakonfigurovat celý ekosystém, aplikace, databáze, cache atd. Teoreticky je to geniální věc. Nehledě na systém máte předpis, který spustíte na jakémkoliv systému a vytvoří vám stejné prostředí pro vývoj. V praxi to už tak veselé nebylo. Je pravda, že jsem Vagrant použil naposledy před několika lety. Problémy byly zpravidla nějaká specifika operačních systému, zvláště Windows. Nebo situace co se musely řešit "hackem", protože ještě neexistovalo nativní řešení a samozřejmě hromada virtuálních mašin, když bylo prostředí pro vývoj rozsáhle. I tak jsem na tom byl nějakou dobu schopný vyvíjet a šlo to docela dobře. Čas pokročil a určitě byla hromada věcí dotažena. Určitě se jedná o funkční řešení.

Scénář 4 - Docker

Jak už název článku napovídá, budeme řešit Docker. Docker používá kontejnery. Kontejner je softwarová jednotka, která zapouzdřuje kód i s jeho závislostmi. Na rozdíl od standardní virtualizace, nerozebíhá znovu celý operační systém, ale používá operační systém hostitele. Nejlíp to asi vysvětlí přímo citace ze stránek Dockeru.

A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.

Container images become containers at runtime and in the case of Docker containers – images become containers when they run on Docker Engine. Available for both Linux and Windows-based applications, containerized software will always run the same, regardless of the infrastructure. Containers isolate software from its environment and ensure that it works uniformly despite differences for instance between development and staging.

from https://www.docker.com/resources/what-container/

V praxi to znamená, že máte v kontejneru souborový systém operačního systému dle libosti. Doinstalujete si potřebné balíčky pro běh vašeho projektu a tento kontejner můžete izolovaně pouštět tam, kde jsou kontejnery podporované. Speciálně Docker funguje pod Linuxem, MacOs i Windows.

+------------++-----------+
|    APP1    ||   APP2    |
+------------++-----------+
+------------++-----------+
|  Bin/Libs  ||  Bin/Libs |
+------------++-----------+
+-------------------------+
|         Docker          |
+-------------------------+
+-------------------------+
|    Operační systém      |
+-------------------------+
+-------------------------+
|         Server          |
+-------------------------+

"Back in my days", když jsem si chtěl na serveru rozjet nějaké služby, buď jsem provozoval nějakou virtualizaci nebo jsem to všechno naplácal do jednoho operačního systému. Jedno ze zásadních úskalí bylo to, že různé služby potřebovaly různé balíky, verze knihoven a míru konfigurace. Pokud člověk nebyl dostatečně obezřetný mohl si "roze***t" celý systém a vše poslat do kytek. V lepším případě byla mašina v jakémsi meta ezo stavu, kdy něco jelo a něco ne.

S Dockerem hromada problémů opadla. Každá služba je izolovaný kontejner, který si své závislosti bere sebou. Pokud něco nefunguje, vadný kontejner se vymaže, ale vše ostatní jede dál. Drtivé množství běžných služeb (wiki, databáze, ...) mají už dnes nachystané a nakonfigurované obrazy. V uvozovkách je stačí jen spustit. Jako všechno si to sebou nese i negativa. Neaktualizované knihovny v kontejneru jsou bezpečnostní riziko. Nebo pokud si nevytváříte kontejner sami tak musíte důvěřovat autorovi, že tam nenasadil nějakou breberku. Ale vždy je něco za něco.

Jak už asi tušíte, z tohoto stručného popisu, použití pro výše popsaný problém bude jasné. Vytvoří se pro projekt Docker kontejner a tak budou všechny závislosti projektu izolovány od hlavního operačního systému. Takhle můžete mít pohodlně puštěné aplikace pod různou verzí NodeJS na jednom stroji. Je to v podstatě jako Vagrant, VirtualBox nebo obecně virtualizace. Akorát teda ne tak úplně. 🙂

Nešpinit systém, na kterém vyvíjíte, závislostmi projektu je podle mě dlouhodobě udržitelná cesta.

Plus mají kontejnery dnes ještě jednu výhodu. Cloudové služby vám zpravidla umožňují posílat kontejnery i do produkce.

Čestná zmínka

Výše uvedené scénáře nejsou určitě jediné, ale jsou to ty, se kterými jsem se setkal osobně.

Minimálně ještě existuje možnost vyvíjet na vzdáleném operačním systému přes SSH. Visual Studio Code tento vzdálený vývoj umožňuje. Jako taky možnost, ale za mě teda trochu exotická. Ale když není zbytí, lepší než drátem do oka.

NodeJS projekt v Dockeru

Toto není kompletní návod pro člověka, který se v životě neotřel o Docker nebo o NodeJS a vývoj API. Do takových podrobností článek nejde. Zabývá se jak rozjet projekt v Dockeru a předpokládá už určité znalosti. Pardon. 🙂

V první řadě budeme potřebovat nainstalovat Docker. Případně na desktopu (a hlavně na Windows) to bude Docker Desktop.

Pokusíme se rozjet vývoj REST API s použitím ExpressJs.

Pro náš projekt budeme mít následující strukturu.

nodejs-docker-workflow \
    .dockerignore
    .env
    Dockerfile
    index.js
    package.json
    package-lock.json

pakcage.json obsahuje konfiguraci projektu.

{
  "name": "nodejs-docker-workflow",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon -L index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.18.1"
  },
  "devDependencies": {
    "nodemon": "^2.0.20"
  }
}

V části závislostí budeme pro náš jednoduchý projekt potřebovat pouze balíček express. V rámci vývojových závislostí (devDependencies) budeme používat nodemon. Ten nám umožní restart serveru, pokud se vyskytne změna v hlídaném adresáři.

index.js obsahuje kód našeho REST API.

const express = require('express')

const app = express()

app.get('/', (req, res) => {
    res.send({
        data: {
            message: 'Hello world!',
            exclamation: '!!!',
        },
    })
})

const port = process.env.PORT || 3000

app.listen(port, () => console.log(`listening on port ${port}`))

Primitivní API vracející "Hello world!".

Dockerfile obsahuje sestavení našeho obrazu kontejneru.

FROM node:16
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . ./
ENV PORT 3000
EXPOSE $PORT
CMD ["npm", "run", "dev"]

FROM node:16 říká, že použijeme základní image, na kterém je už nachystán NodeJS verze 16.

WORKDIR /app nás v rámci kontextu přesune do složky /app.

COPY package*.json . překopíruje do obrazu do /app soubor package.json.

RUN npm install spustí instalaci závislostí na základe package.json.

COPY . ./ překopíruje soubory z aktuálního adresáře do obrazu do /app.

ENV PORT 3000 vytvoří proměnou prostředí.

CMD ["npm", "run", "dev"] spustí skript definovaný v package.json, který spustí nodemon.

.dockerignore obsahuje seznam souboru a složek co se nebudou kopírovat do obrazu.

node_modules
Dockerfile
.dockerignore
.git
.gitignore
README.md
docker-compose*

.env je seznam proměnných prostředí, které chceme aplikovat na kontejner.

PORT=4000

Základní projekt máme nachystaný. A sestavíme na základě Dockerfile obraz pro náš kontejner.

docker build -t node-app-image .

Následně pak můžeme překontrolovat, že obraz skutečně existuje.

docker image ls

Obraz je nachystaný a můžeme spustit samotný kontejner.

# WINDOWS %cd%
# POWERSHELL ${pwd}
# MAC, LINUX $(pwd)

# --env PORT=4000
# --env-file ./.env

docker run -p 3000:4000 -d --name node-app --env-file ./.env -v %cd%:/app -v /app/node_modules node-app-image

-p 3000:4000 přesměruje port 3000 z hostitelského systému na port 4000 Docker kontejneru.

-d spustí Docker kontejner na pozadí.

--name node-app pojmenuje kontejner.

--env-file ./.env nastaví proměnné systému na základě souboru .env.

-v %cd%:/app zajistí zrcadlení aktuálního adresáře a jeho změny do /app v kontejneru.

-v /app/node_modules vytvoří volume pro node moduly. Díky tomu se nestane to, že přes zrcadlený adresář pošleme příkaz k jejich smazání v kontejneru. Je to trochu "ohák", ale funční.

node-app-image je název obrazu na základě kterého vytváříme kontejner.

Pokud nedostaneme nějaké chybové hlášení, můžeme zkontrolovat, že vše jede.

Můžeme se podívat na aktuálně běžící kontejnery.

docker ps

A můžeme také zkontrolovat logy pro konkrétní kontejner.

docker logs node-app

Když do prohlížeče zadáme localhost:3000 dostaneme následující.

{"data":{"message":"Hello world!","exclamation":"!!!"}}

Pokud v souboru index.js upravíme odpověď serveru, nodemon na to zareaguje a restartuje API s aktuální změnou.

Jestliže se potřebujeme "přihlásit" dovnitř kontejneru do příkazové řádky, použijeme docker exec.

docker exec -it node-app bash

V této chvíli máme plně funkční NodeJS projekt v Dockeru. Pokud přidáme nebo odebereme balíčky, musím znovu sestavit obraz pomocí docker build -t node-app-image . a Docker kontejner spustit.

Předtím je teda nutné kontejner zabít, to uděláme pomocí docker rm.

docker rm node-app -fv

-fv odstraní i běžící kontejner (nemusíme zastavovat) a na něj navázané anonymní volumes (svazky).

Tohle je taková "základní" verze. Spouštění Docker kontejneru, s veškerou konfigurací v příkazové řádce může být po čase otrava. Jednodušším řešením je použití Docker-Compose.

V našem projektu vytvoříme soubor docker-compose.yml.

version: "3"
services:
  node-app:
    container_name: node-app
    build: .
    ports:
      - "3000:4000"
    volumes:
      - ./:/app
      - /app/node_modules
    env_file:
      - ./.env
#    environment:
#      - PORT=4000 

version: "3" je verze zápisu Docker Compose souboru.

node-app: uvozuje sekci našeho kontejneru.

container_name: node-app pojmenuje náš kontejner. Pokud ho nepojmenujeme sami, Docker to udělá za nás.

build: . sestaví obraz pomocí Dockerfile.

ports: přesměrování portů.

volumes: seznam volumes.

env_file: nastavuje proměnné prostředí.

Docker Compose soubor jen kopíruje to, co jsme nastavovali pro docker run. Ale takhle nám zůstane nastavení pěkně a strukturovaně uloženo.

Předpis spustíme pomocí příkazu docker-compose.

docker-compose up -d

Pokud přidáme parametr --build, tak se při každém spuštění znovu sestaví obraz.

docker-compose up -d --build

Pomocí docker-compose provádíme i smazání.

docker-compose down -v

-v jako v předchozím případě smaže i připojené anonymní volumes.

Tohle je už o něco lepší verze, ale nepočítá s tím, že bychom chtěli různá prostředí. Například development a production. Budeme muset upravit Dockerfile, docker-compose.yml a přidat docker-compose.dev.yml a docker-compose.prod.yml.

Do Dockerfile přidáme podmínku pro různá prostředí.

FROM node:16
WORKDIR /app
COPY package*.json .

ARG NODE_ENV
RUN if [ "$NODE_ENV" = "development" ]; \
        then npm install; \
        else npm install --only=production; \
        fi

COPY . ./
ENV PORT 3000
EXPOSE $PORT
CMD ["node", "index.js"]

ARG NODE_ENV definujeme použití argumentu NODE_ENV.

RUN if [ "$NODE_ENV" = "development" ]; \ na základě aktuální typu prostředí provedeme klasický npm install nebo produkční.

CMD ["node", "index.js"] je příkaz do produkčního prostředí, protože nespouštíme nodemon. Každopádně ho stejně budeme definovat znovu v Docker Compose souborech.

docker-compose.yml trošku zeštíhlíme a necháme v něm jen společná nastavení pro všechna prostředí.

version: "3"
services:
  node-app:
    container_name: node-app
    build: .
    ports:
      - "3000:4000"
    environment:
      - PORT=4000  

docker-compose.dev.yml nastavím pro naše development prostředí.

version: "3"
services:
  node-app:
    build:
      context: . 
      args:
        NODE_ENV: development
    volumes:
      - ./:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development  
    command: npm run dev

Všimněte si, že jsme rozšířili definici build a přidali argument NODE_ENV, který se používá v Dockerfile. Nastavení volumes je stejné jako předtím a přepsali jsme CMD v Dockerfile na náš development příkaz.

docker-compose.prod.yml bude jednodušší, protože pro produkci nepotřebujeme zrcadlit adresáře.

version: "3"
services:
  node-app:
    build:
      context: . 
      args:
        NODE_ENV: production
    environment:
      - NODE_ENV=production
    command: node index.js

Principiálně je to to samé co docker-compose.dev.yml.

Pokud budeme chtít spustit development verzi, zavoláme.

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Popřípadě, pokud chceme spustit i vytváření obrazu.

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

Odstranění kontejneru provedeme promocí.

docker-compose -f docker-compose.yml -f docker-compose.dev.yml down -v

Pro produkční build to bude analogické.

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
docker-compose -f docker-compose.yml -f docker-compose.prod.yml down -v

TADÁ a to je vše přátele. Aplikace funguje pořád stejně, ale už můžeme rozlišovat mezi development a production prostředtím.

---

ad1) Článek popisuje pouze absolutní základ, pravá síla Dockeru se projeví ve chvíli, kdy si nakonfigurujete kompletní ekosystém a budete ho schopni jednoduše replikovat.

ad2) Článek ukazuje situaci, kdy nebudete mít na svém stroji nainstalován NodeJS a nepustíte npm install na svém stroji. Tím si nevygenerujete package-lock.json. To může být problém při generování produkčních kontejnerů. package-lock.json obsahuje deterministický popis závislostí. Do produkce chcete jít s takovým stromem závislostí, který už máte odzkoušený. Pro doplnění citace z docs.npm.com.

package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.

from https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json

Proto je vhodnější postup na hostitelské systému používat npm i pro instalaci nových balíčku do projektu. Tím se bude generovat i package-lock.json. Toto nijak neomezuje používání rozličných verzí NodeJS v kontejnerech.

ad3) Docker se chová tak, že spustí příkaz a když doběhne, tak se vypne. V případě, že rozjíždíte NodeJs API, tak je to jedno. Tam se předpokládá, že pouštíte nějaký nodemon nebo něco co udrží API v běhu. Pokud ale chcete vyvíjet něco co neběží ve smyčce a z Dockerfile odeberete CMD příkaz, tak se Docker container spustí a úspěšně ukončí. Jde tím předejít přidáním parametru tty.
Ten zajistí, že se kontejner hned neukončí.

Pro docker-compose:

mydocker:
    tty: true

Pro docker run:

docker run -d --tty ......