When you use an app, whether it's a web app or a desktop app, that communicates with a remote server over the internet, you can be 99% sure there is an API server involved. API servers are the hidden part of the application where almost all the magic happens. One option for creating APIs is NestJS, and we will explore it a little bit.

Key Benefits of NestJS:

• Scalability: NestJS is built with scalability in mind, making it easy to manage large-scale applications. Its modular architecture allows developers to split their applications into small, reusable modules.
• TypeScript Support: As a framework built on top of TypeScript, NestJS offers all the benefits of TypeScript, including type safety, improved code readability, and maintainability.
• Extensive Ecosystem: NestJS has a rich ecosystem of libraries and tools, which simplifies the development process. It integrates seamlessly with other popular libraries and frameworks like Express, Fastify, and more.
• Ease of Use: The framework is designed to be developer-friendly, with a well-documented API and a robust CLI that helps in generating boilerplate code, thereby reducing development time.
• Dependency Injection: NestJS uses a powerful dependency injection system, which makes it easier to manage dependencies and promotes better code organization and testability.

Disclaimer: This article is not primarily intended for people who are new to programming. It is written with the expectation of some experience in programming. To be honest, my motivation for writing this article is to compile my NestJS developer notes, and I've chosen to present them in article form. It will not explain NestJS in detail, nor its architecture. Instead, it will focus on solving specific problems I have encountered. I hope you find it useful.

In Chapter 1, we will install NestJS and bring the API server to life.

Make sure you are using the latest LTS version of NodeJS.

For project creation and management, we will use @nestjs/cli. The easiest way is to install it globally.

npm i -g @nestjs/cli

Then, in your projects folder, simply use the nest command to create a new project.

nest new hardwired-nestjs-api-chapter-01

You will be asked which package manager you want to use. I use npm.

When it is done, just delete the .spec.ts files from the src folder. We don't care about tests right now. A bunch of things are already set up, like prettier, eslint, and TypeScript configuration. Useful scripts are prepared in package.json.

"scripts": {
    "build": "nest build",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "start": "nest start",
    "start:dev": "nest start --watch",
    "start:debug": "nest start --debug --watch",
    "start:prod": "node dist/main",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage",
    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  },

For now, we only need start:dev to run the development version. In the src folder, you can find main.ts, which is the entry point to our API, along with app.controller.ts, app.module.ts, and app.service.ts. You can find a perfect explanation of the NestJS architecture in the chapters Controllers, Providers, and Modules in the NestJS documentation.

main.ts is pretty simple. Just includes @netjs/core, app.module and bootstrap our application.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

When you run npm run start:dev, the API will run on port 3000, and you will be able to access it at http://localhost:3000.

Controllers are where you define your routes. In app.controller.ts, there is one GET route.

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

The @Get decorator without parameters in app.controller.ts indicates that you will access this route with /. It's the root route, and you can access it at http://localhost:3000. This route calls the service method getHello(), which returns the string Hello World!. Services are where your business logic resides.

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

You can access http://localhost:3000 in your browser, and if the development server is running, you will see Hello World!. However, as an API developer, you may want a better way to call your API during development. I recommend using Insomnia.

When you call http://localhost:3000 using Insomnia, you will get the same result as in the browser. However, as you add more routes and JSON responses, you will appreciate the usefulness of Insomnia.

Hello World!

Hello World is okay, but not very useful. Let's build something more meaningful.

First, we should discuss how to organize our routes to avoid a mess later. A good way is to organize them into resources. A resource can be user, article, comment, etc. For resource bases, we will use plurals, for example, users, articles, and comments. It is a good practice to follow REST principles when creating an API. One of my favorite articles on this topic is Best Practices for Designing a Pragmatic RESTful API.

Sometimes it is easier for programmers to use just GET and POST methods for all routes, but this does not adhere to RESTful principles. RESTful principles provide strategies to handle CRUD actions. It is better to use the full potential of HTTP methods. For example, when we take the resource user:

• GET /users - retrieves a list of users
• GET /users/1 - retrieves the user with id 1
• POST /users - creates a new user
• PUT /users/1 - updates the user with id 1
• PATCH /users/1 - partially updates the user with id 1
• DELETE /users/1 - deletes the user with id 1

You can also combine resources. For instance, to get the articles for a user, one route could be GET /users/1/articles.

If you want to like an article, the API endpoint could be PUT /articles/1/like. You can use aliases, filtering, sorting, limiting, and pagination constructs, but this is a complex and highly opinionated field suitable for many articles. I think the best quick dive is provided in the article I mentioned earlier, written by Vinay Sahni.

Earlier in the article, I said "Let's build something more meaningful," but that was a lie. For a quick demonstration of how to create a resource and follow methods, we will use something completely useless.

We will create a route GET /zodiac-signs. This route will return a list of zodiac signs with date ranges. I borrowed the list from here.

To create a NestJS resource, we will use the nest cli.

nest g res zodiac-signs --no-spec

• nest - nest command
• g - generate
• res - resource
• zodiac-sign - resource-name
• --no-spec - do not generate tests

After you enter the command, you will be asked what type of transport layer you want to use. Choose REST API. The next question will be whether you would like to create CRUD entry points. I choose no; I will create them on my own.

When it is done, in your src folder, you will see a folder named zodiac-signs, and it will contain zodiac-signs.controller.ts, zodiac-signs.module.ts, and zodiac-signs.service.ts.

Nest CLI automatically connects your new resource/module to the app.

We will start with zodiac-signs.service.ts.

import { Injectable } from '@nestjs/common';

@Injectable()
export class ZodiacSignsService {
    signs = {
        aries: {
            symbol: '♈',
            dateMin: '2000-03-21',
            dateMax: '2000-04-20',
        },
        taurus: {
            symbol: '♉',
            dateMin: '2000-04-21',
            dateMax: '2000-05-21',
        },
        gemini: {
            symbol: '♊',
            dateMin: '2000-05-22',
            dateMax: '2000-06-21',
        },
        cancer: {
            symbol: '♋',
            dateMin: '2000-06-22',
            dateMax: '2000-07-22',
        },
        leo: {
            symbol: '♌',
            dateMin: '2000-07-23',
            dateMax: '2000-08-22',
        },
        virgo: {
            symbol: '♍',
            dateMin: '2000-08-23',
            dateMax: '2000-09-23',
        },
        libra: {
            symbol: '♎',
            dateMin: '2000-09-24',
            dateMax: '2000-10-23',
        },
        scorpio: {
            symbol: '♏',
            dateMin: '2000-10-24',
            dateMax: '2000-11-22',
        },
        sagittarius: {
            symbol: '♐',
            dateMin: '2000-11-23',
            dateMax: '2000-12-21',
        },
        capricorn: {
            symbol: '♑',
            dateMin: '2000-12-22',
            dateMax: '2000-01-20',
        },
        aquarius: {
            symbol: '♒',
            dateMin: '2000-01-21',
            dateMax: '2000-02-19',
        },
        pisces: {
            symbol: '♓',
            dateMin: '2000-02-20',
            dateMax: '2000-03-20',
        },
    };

    findAll() {
        return this.signs;
    }
}

In the ZodiacSignsService class, we have our logic. The list of signs is stored as a class property named signs. The method that returns this list is findAll(). It is a good practice for the route GET /zodiac-signs to use the service method findAll, and for GET /zodiac-signs/:name to use the service method findOne. This uniform naming system will help you orient yourself in a large code base.

Next will be zodiac-signs.controller.ts.

import { Controller, Get } from '@nestjs/common';
import { ZodiacSignsService } from './zodiac-signs.service';

@Controller('zodiac-signs')
export class ZodiacSignsController {
  constructor(private readonly zodiacSignsService: ZodiacSignsService) {}

  @Get()
  findAll() {
    return this.zodiacSignsService.findAll();
  }
}

We create a method findAll decorated with @Get decorator, which, without parameters, instructs the app router to point to the findAll method in the ZodiacSignsController in response to a GET /zodiac-signs request.

That's all for now. Make sure the development server is running (npm run start:dev). Then, you can access http://localhost:3000/zodiac-signs. The expected result is the same JSON as we have in ZodiacSignsService.

Okay, it's not much, but it's enough to get started. In the next chapter, we'll take a look at DTOs (Data Transfer Objects).

You can find project on my GitHub.

Happy coding!

The post NestJS Chapter 01 – New Project first appeared on Hard Wired.

TypeScript compared to JavaScript is a little bit more complex. If you do server-side JavaScript, you just call node your-script.js and it runs. When you want to use TypeScript, you need to install a few things and do a few steps to make your code runnable.

Make sure you have installed the latest version of nodejs on your system.

Create your project folder, change the current working directory, and install typescript as your development dependency.

npm i -D typescript

Initialize your nodejs project.

npm init

Then use npx to initialize a new typescript project.

npx tsc --init

A bunch of files should be in your project:

• package.json
• package-lock.json
• tsconfig.json

Edit tsconfig.json, find outDir, and change it if you do not want compiled files in your root directory. Change it to the build folder.

...
outDir": "./build",   /* Specify an output folder for all emitted files. */
...

Now it's time to create your first TypeScript code.

Create a file index.ts and just put some random code.

async function main() {
    const i: number = 1;

    console.log('Random stuff', i);
}

main()

Save it and then you can do a manual compilation.

npx tsc

This compiles your project and the output will be stored in the build folder. You will find the file index.js there. Do a test run with node ./build/index.js.

In the console, you should see:

Random stuff 1

You can use npx tsc -w to activate watch mode. When you change anything in your project, it will be recompiled automatically.

To make it a little bit easier, you can edit the scripts property in package.json to merge compilation and run into one command.

...
"scripts": {
        "start": "npx tsc && node ./build/index.js"
},
...

When you call npm run start, your project will be compiled and run.

During code development, you should use a linter to check your code using certain rules to avoid code inconsistency. An easy way is to use Google TypeScript Style.

Install gts as a development dependency.

npm i -D gts

Then initialize gts with npx.

npx gts init

It will ask you some questions. If your typescript version is higher than suggested, just say no. Then you will be asked about updating tsconfig.json, say yes.

Some big changes will be made.

The src folder will be created with an index.ts file in it. Remove your old index.ts from the root folder.

In package.json, update your start script.

...
"start": "npx tsc && node ./build/src/index.js",
...

Make sure you have eslint support activated in your editor

You will get an index.ts example file in the src directory. It is all wrong. If you have eslint support activated in your editor, it should scream at you with lots of errors.

console.log("Try npm run lint/fix!");

const longString = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut aliquet diam.';

const trailing = 'Semicolon'

            const why={am:'I tabbed?'};

const iWish = "I didn't have a trailing space..."; 

const sicilian = true;;

const vizzini = (!!sicilian) ? !!!sicilian : sicilian;

const re = /foo   bar/;

export function doSomeStuff(withThis: string, andThat: string, andThose: string[]) {
    //function on one line
    if(!Boolean(andThose.length)) {return false;}
    console.log(withThis);
    console.log(andThat);
    console.dir(andThose);
    console.log(longString, trailing, why, iWish, vizzini, re);
    return;
}
// TODO: more examples

Just run npm run fix to let gts fix your code. You will get this:

console.log('Try npm run lint/fix!');

const longString =
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer ut aliquet diam.';

const trailing = 'Semicolon';

const why = {am: 'I tabbed?'};

const iWish = "I didn't have a trailing space...";

const sicilian = true;

const vizzini = sicilian ? !sicilian : sicilian;

const re = /foo {3}bar/;

export function doSomeStuff(
  withThis: string,
  andThat: string,
  andThose: string[]
) {
  //function on one line
  if (!andThose.length) {
    return false;
  }
  console.log(withThis);
  console.log(andThat);
  console.dir(andThose);
  console.log(longString, trailing, why, iWish, vizzini, re);
  return;
}
// TODO: more examples

If it is working, you have just created your typescript project with a linter. It is a good thing to configure your code editor to perform npm run fix with every save.

Enjoy TypeScript coding.

The post How to create a new TypeScript project first appeared on Hard Wired.

ROCK Pi S je SBC (jednodeskový počítač) od společnosti Radxa založený na Rockchip RK3308. Je vybaven 64bitovým čtyřjádrovým procesorem, USB, ethernetem, bezdrátovým připojením a jádrem detekce hlasu o velikosti 1,7 palce, takže je ideální pro IoT a hlasové aplikace. ROCK Pi S se dodává ve dvou velikostech paměti RAM 256 MB nebo 512 MB DDR3 a pro operační systém a úložiště používá kartu uSD. Volitelně může ROCK Pi S poskytnout verzi s integrovaným úložištěm s 1Gb/2Gb/4Gb/8Gb NAND flash. Mezi podporované operační systémy patří Debian, Ubuntu, Armbian, Diet Pi a další.

Rock Pi S obsahuje procesor RK3308 který má čtyři jádra s frekvencí až 1.3 GHz. Na takhle malé desce jednodeskového počítače najdete i ethernet konektor (100 Mbps), USB-A konektor (USB 2.0), Wi-Fi konektivitu 802.11 b/g/n a Bluetooth 4.0.

Verze Rock Pi S

Výkon samotného ARM procesoru je u všech verzí stejný, rozdíl je jen v kapacitě RAM a to buď 256 MB nebo 512 MB. U posledních dvou verzí s 512 MB ram máme možnost výběru buď to 1, 2, 4 a 8 GB NAND flash paměti.

Napájení

ROCK Pi S využívá port USB Type-C pro napájení i komunikaci.

Pokud chcete ROCK Pi S napájet samostatně, můžete použít napájecí adaptér 5V/1A nebo 5V/2A s porty USB Type-C. Můžete také použít napájecí adaptér USB PD/QC, aniž byste se museli obávat poškození desky, protože adaptér PD/QC detekuje, že ROCK Pi S podporuje pouze 5V, takže adaptér bude vydávat 5V.

ROCK Pi S lze napájet přímo z USB portů PC/laptopu. Pokud ke komunikaci s hostitelským počítačem potřebujete také ROCK Pi S, stačí vám kabel USB typu C pro typ A.

Pokud používáte funkci PoE poskytovanou ROCK Pi S, můžete napájet ROCK Pi S vložením DV +5V přímo do PIN#2 26-PIN HEADER 1. GND pin jako PIN#6.

Procesor

Rockchip RK3308 Soc použitý v ROCK Pi S RK3308 je vysoce výkonný čtyřjádrový aplikační procesor s frekvencí 1.3 Ghz, navržený pro inteligentní hlasovou interakci, zpracování audio vstupu/výstupu a další digitální multimediální aplikace. Vestavěná bohatá zvuková rozhraní, jako jsou I2S, PCM, TDM, PDM, SPDIF, HDMI ARC, mohou splňovat různé vývojové zvukové aplikace, snížit složitost vývoje hardwaru a náklady na vývoj.

Pokud si pořídíte tuto super jednodeskoví počítač, nezapomeňte si z PRINTABLES stáhnout box na tento tip desky. Máte na výběr verzi s anténou a bez antény.

The post Jednodeskový počítač – RADXA Rock Pi S first appeared on Hard Wired.

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 ......

The post NodeJS develompent v Dockeru first appeared on Hard Wired.