Подготовка шаблона приложения на Typescript с Nest, Nuxt 3 и Docker

Решил описать свой подход построения окружения на Typescript с Nest на бекенде, Nuxt (SPA) на фронтенде. Все заворачивается в один docker-образ и запускается как standalone приложение c nginx, healthcheck’ами, тестами и ш…широкой сферой применения.

Делал это в качестве фундамента для будущих проектов или с целью изучения Nest, Nuxt 3 с composable функциями. Можно использовать это как инструкцию к настройке подобной архитектуры, можно взять за основу код с github.

Архитектура проекта

Шаблон приложения поставляется в виде одного docker-образа, в котором установлен nest+nginx и собраны backend и frontend.

Файловая структура

Для начала опишу из как выглядит архитектура проекта.

└── application/
    ├── backend/
    │   └── NEST приложение
    ├── frontend/
    │   └── NUXT приложение
    ├── docker/
    │   └── nginx/
    │       └── conf.conf
    ├── .dockerignore
    ├── .gitignore
    ├── docker-compose.yml
    ├── Dockerfile
    └── readme.md

• backend — стандартное nest приложение с добавленным serve-static модулем.

• frontend — стандартное nuxt приложение с добавленным и настроенной связью с backend

• docker — папка с конфигами, которые пойдут в docker образ (в текущей версии только nginx)

• Dockerfile — указания по сборке докер-образа

• docker-compose.yml — файл для запуска проекта

Весь проект доступен на github, его можно склонировать, запустить командой docker-compose up -d (подробнее про запуск написал в конце статьи) и запустить готовый к расширению шаблон приложения. Ниже я описал что именно изменено в стартовых приложениях и каким образом настроена связь между ними

В этом шаблоне нет базы данных и каких-либо других сторонних зависимостей, чтобы не ограничивать набор компонентов для дальнейшей разработки.

Процесс обработки запросов

В качестве сервера, принимающего запросы используется Nginx. Он раздает статику собранного frontend приложения и перенаправляет запрос на бекенд, если URL запроса начинается на /api

Таким образом может быть 2 типа запроса.

Статический:

И запрос к API:

Подготовка Backend сервиса

За основу взят стартовый набор nest:

$ npm i -g @nestjs/cli
$ nest new backend

Дальше необходимо сделать некоторые доработки. Первым делом в main.ts прописываем порт по умолчанию на 3001, добавляем префикс /api. Таким образом main.ts обретает следующий вид:

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const port = process.env.APP_PORT || 3001;
  app.setGlobalPrefix('api');
  app.enableCors();
  await app.listen(port);
}
bootstrap();

Настройка static директории

В папку static будет переноситься статичный html/js/css бандл с nuxt приложением и потом раздаваться как статичный сайт при запуске проекта без nginx.

Да, при прочих равных, стоит запускать проект с nginx и для этого не нужно переносить в папку static ничего.

Но на то это и бойлер, что я заранее не знаю как он будет и где запускаться. Может быть, в каких то ситуациях, при малых нагрузках, будет достаточно запуска чистого Nest.

Для того, чтобы nest раздавал статику достаточно подключить модуль serve-static внутрь AppModule

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ServeStaticModule } from '@nestjs/serve-static';
import * as path from 'path';

@Module({
  imports: [
    ServeStaticModule.forRoot({
      rootPath: path.join(__dirname, '..', 'static'),
      serveRoot: '/',
      exclude: ['/api*'],
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Обратите внимание на блок exclude: ['/api*']. Это нужно для того, чтобы статика раздавалась на всех ссылках, кроме /api — при запуске проекта по пути /api будет размещаться само nest приложение.

В саму папку static размещаем .gitignore с двумя строчками

*
!index.html

И index.html, который будет использоваться только при разработке и при сборке конечного docker-образа в эту папку будет складываться html/js/css интерфейса.

Небольшое отступление по поводу префикса к api

В nest можно реализовать префикс /api двумя способами:

• в каждом контроллере приписывать /api в @Controller('/api/controller-route')

• прописать на уровне nest приложения глобальный префикс

Я в своем шаблоне использую второй способ. Для его реализации нужно сделать следующее:

1. Прописать в main.ts строчку app.setGlobalPrefix('api');

2. Поправить e2e тест, чтобы в нем тоже создавалось приложение с префиксом и поправить сами тесты.

Поскольку я стараюсь разрабатывать через e2e тесты и тестов в проектах может быть очень много, я сразу выношу в отдельную функцию создание тестового приложения:

export async function createTestingApp() {
	return (
	  await Test.createTestingModule({
	    imports: [AppModule],
	  }).compile()
	)
	  .createNestApplication()
	  .setGlobalPrefix('api');
}

Дальше я уже, в тестах, использую эту функцию вместо штатной инициализации приложения:

import { createTestingApp } from './utils/create-testing-app';

// .....

beforeEach(async () => {
  app = await createTestingApp();
  await app.init();
});

Настройка тестового окружения

Я уже немного затронул тестовое окружение в предыдущем блоке, но по тестам я сделал еще небольшие изменения.

• удалил стандартный spec файл у контроллера, т.к. сам предпочитаю e2e тесты и узкие тесты пишу в редких случаях

• поменял формат jest.e2e.config.json на js, тк, зачастую, в проектах приходится добавлять динамические конфигурации и IDE js формат считывает сразу.

• поправил базовый тест с указанием /api в самих тестах

Подготовка Frontend

В качестве фронта берется Nuxt 3 и ставится через официальную команду

yarn create nuxt-app frontend

Важный момент: я не буду использовать Nuxt с SSR, т.к. у меня планируется чисто SPA подход (когда браузер загружает целиком весь код к себе и дальше уже рендерит интерфейс).

Да, SSR классно и здорово, но считаю его уместным в проектах с необходимостью поддерживать SEO или если необходимо часть логики отображения скрыть от пользователя (чтобы не показывать какие-то переменные окружения).

В любом случае, при необходимости, данный стартовый набор можно “переобуть” на работу с SSR. Что бы выключить SSR режим надо в nuxt.config.ts указать ssr: false

Пара слов про Options и Composition

Если вы давно знакомы с Vue, то вы должны знать, что раньше все компоненты можно было делать vue компоненты только через Options подход (создавать объект с полями data, computed и тд). Сейчас появился подход через setup функцию и мне до конца не ясны прелести этого подхода.

Я же остановился, пока что, на подходе через options и постепенно внедряю compose функции в небольших проектах. В текущем наборе я выбрал Composition подход, т.к. тут функционала почти нет и заодно можно попробовать.

Подключение NuxtPage

Изначально в App.vue не проставлен NuxtPage компонент и, следовательно, маршрутизация через файлы в pages работать не будет. Поэтому необходимо App.Vue привести к следующему виду:

<template>
  <div>
    <NuxtPage />
  </div>
</template>

После чего каждый файл в папке pages/ будет открываться по одноименной ссылке в браузере. Подробнее можно прочитать здесь.

Коннектор к API

Для реализации бизнес-логики во Vue 3 разработчиками можно использовать Composable функции. Раньше я всегда делал подобные вещи в виде отдельного плагина с подстановкой хедера авторизации + указания baseUrl из env переменной.

Сейчас я сделаю по-современному через создание своей composable функции, расширяющей useFetch. В Nuxt composables создаются автоматически, создав файл в папке composables.

// frontend/composables/api.ts
import { UseFetchOptions } from '#app';
import { NitroFetchRequest } from 'nitropack';
import { KeyOfRes } from 'nuxt/dist/app/composables/asyncData';

export function useApiRequest<T>(
  request: NitroFetchRequest,
  opts?:
    | UseFetchOptions<T extends void ? unknown : T,
    (res: T extends void ? unknown : T) => T extends void ? unknown : T,
    KeyOfRes<(res: T extends void ? unknown : T) => T extends void ? unknown : T>>
    | undefined
) {
  const config = useRuntimeConfig();

  return useFetch(request, {baseURL: config.public.baseURL, ...opts});
}

Чтобы конструкция config.public.baseURL работала, необходимо расширить nuxt.config.ts следующим образом:

export default defineNuxtConfig({
  ssr: false,
  runtimeConfig: {
    public: {
      baseURL: process.env.API_URL || 'http://localhost:3001/',
    },
  },
})

И теперь, по умолчанию, baseURL будет равен http://localhost:3001/, чтобы, при разработке, стучаться в отдельно запущенный Nest. При сборке буду менять его на /api.

Пример использования API вызова

В качестве примера я оставил в компонент, который делает вызов в /api/test и проставляет в разметку все состояния запроса:

<template>
  <div>
    <template v-if="pending">
      Loading
    </template>
    <template v-else>
      <template v-if="data">
        Api result: {{ data }}
      </template>
      <template v-else-if="error">
        Api ERROR: {{ error }}
      </template>
      <button @click="refresh()">refresh</button>
    </template>
  </div>
</template>

<script setup>
import { useApiRequest } from '../composables/api'

const { data, pending, error, refresh } = useApiRequest('/api/test')
</script>

Подготовка Docker-образа и docker-compose.yml

В своем личном блоге я писал и снимал про это видео, что небольшие проекты я разворачиваю достаточно топорным способом:

• подготовить docker образ

• подготовить docker-compose

• развернуть на сервере nginx-proxy c acme-companion

• запускать проект обычным docker-compose up -d и наслаждаться рабочим продуктом

Да, это конечно не Kubernetes и не супер отказоустойчивая архитектура. Но такой подход позволяет на VPS на 400р в месяц запустить десяток подобных проектов для личного использования.

Основная идея сборки состоит из следущих этапов:

1. Собрать frontend (html, js, css)

2. Собрать backend

3. Подсунуть в backend файлы из frontend в папку static

4. Собрать nginx образ, который будет разбирать траффик на статику и логику

Dockerfile с multi-stage build

В проекте я использую node 16 на базе образа alpine. Поэтому начинаем Dockerfile со строчек

FROM node:16-alpine as base-builder
WORKDIR /app

Для начала нужно собрать frontend — подтянуть зависимости, собрать html, js, css.

FROM base-builder as build_fe
WORKDIR /app
COPY ./frontend/package.json ./frontend/yarn.lock* ./
RUN yarn install
ADD ./frontend ./
RUN yarn generate

По итогу в этом промежуточном образе у нас будет собранный frontend в папке /app/dist

Далее собираем backend

FROM base-builder as build_be
WORKDIR /app
COPY ./backend/package.json ./backend/yarn.lock* ./
RUN yarn install
ADD ./backend ./
RUN yarn build

И получаем промежуточный образ только с backend. Теперь осталось собрать воедино в следующий промежуточный образ, который будет на 3001 порту слушать все запросы:

FROM node:16-alpine as finalNode
WORKDIR /app
COPY --from=build_be /app /app
COPY --from=build_fe /app/dist /app/static
CMD yarn start

Я до конца не определился в необходимости этого этапа и, честно говоря, его можно и не делать. У нас, в итоге, получается backend, который умеет также отдавать статику приложения — то есть полностью самостоятельно рабочий docker-образ с приложением, который может работать без nginx. Но именно в рамках текущей статьи эта возможность не используется

Теперь осталось собрать ту часть, которая будет с nginx:

FROM nginx:alpine as finalNginx
WORKDIR /usr/share/nginx/html
RUN rm -rf ./*
COPY --from=finalNode /app/static .
COPY ./docker/nginx/conf.conf /etc/nginx/conf.d/default.conf
CMD ["nginx", "-g", "daemon off;"]

Также надо не забыть положить файл конфигурации nginx по указанном пути:

# docker/nginx/conf.conf
server {
  listen 80 default_server;
	root /usr/share/nginx/html;

  client_max_body_size 20M;

  location / {
    root   /usr/share/nginx/html;
    index  index.html index.htm;
    try_files $uri $uri/ /index.html;
  }

  location /api {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://node:3001;
  }
}

Теперь мы, в рамках одного Dockerfile получили полную сборку всего, что нужно для работы приложения.

Итоговый Dockerfile можно посмотреть в github репозитории.

Подготовка docker-compose.yml

Как я писал выше, я запускаю подобные проекты на сервере, используя nginx-proxy. Так что, первым делом, в конце файла надо объявить сеть reverse-proxy, через которую будет идти подключение из внешнего мира к моему контейнеру с nginx.

version: "3.8"
services:
# тут будут сервисы
networks:
  reverse-proxy:
    external:
      name: reverse-proxy
  back:
    driver: bridge

Также я добавил сеть back — это изолированная сеть, через которую между собой будут общаться nginx и backend.

Теперь опишем как мы будем запускать наш образ с той частью, которая отвечает за backend:

node:
  build:
    context: .
    target: finalNode
  networks:
    - back
  expose:
    - 3001
  restart: always
  environment:
    - APP_PORT=3001
  healthcheck:
    test: wget --no-verbose --tries=1 --spider <http://localhost:3001> || exit 1
    timeout: 3s
    interval: 3s
    retries: 10

По порядку о каждом параметре:

• build

  • context — что будет являться текущей директорией при сборке Dockerfile

  • target — какую часть multi-stage build нужно запускать в этом месте. В данном случае мы указываем, что собирать нужно все до finalNode

• networks

  • тут мы указываем только back, т.к. во внешний мир контейнер ходить не будет и нужен только доступ от nginx к этому контейнеру.

• expose

  • этот пункт открывает доступ другим контейнерам в сети по перечисленным портам. В данном случае мы сообщаем, что в сети back контейнеры могут подключаться на 3001 порт

• restart: always

  • сообщаем, что этот контейнер надо перезапускать всегда. Даже после перезапуска сервера проект будет запущен

  • будет работать до тех пор пока не выключим его командой docker-compose down

• environment

  • передача переменных окружения в сам процесс node

  • в нашем случае только указываем порт, на котором мы хотим, чтобы backend был запущен

• healthcheck

  • прекрасный инструмент для контроля работоспособности контейнера

  • test — команда, от которой мы ожидаем exit-code = 0 (какие есть еще можно прочитать здесь)

  • timeout — время, которое может выполняться команда. Если команда зависла на больший срок, то проверка считается не пройденой

  • interval — с какой частотой стоит выполнять команду, чтобы быть уверенным, что контейнер работает

  • retries — после скольких неудачных ответов сервер помечается “нерабочим”.

Теперь добавим блок с запуском nginx:

nginx:
  build:
    context: .
    target: finalNginx
  networks:
    - reverse-proxy
    - back
  expose:
    - 80
  restart: always
  depends_on:
    node:
      condition: service_healthy
  environment:
    - VIRTUAL_HOST=${DOMAIN}
    - VIRTUAL_PORT=80
    - LETSENCRYPT_HOST=${DOMAIN}
    - LETSENCRYPT_EMAIL=test@test.ru

Подробнее:

• build тоже самое, что в node сервисе, только указан другой target, т.к. нам нужно получить ту часть, которая связана с nginx

• networks тут теперь 2 сети:

  • reverse-proxy сеть, через которую будет доступ от контейнера nginx-proxy

  • back та сеть, в которой есть контейнер node чтобы можно было пересылать запросы ему

• expose сообщаем всем в сетях, что в этот контейнер можно стучаться на 80 порт. Это нужно nginx-proxy для обработки запросов

• restart аналогично сервису node

• depends_on тут мы указываем от каких сервисов мы зависим

  • если это не указать, то nginx будет запускаться вместе с остальными и может получиться ситуация, в которой node еще не запущен, а nginx уже готов принимать запросы, что нехорошо

  • поэтому мы указываем, что зависит от node сервиса

  • зависимость можно считать удовлетворенной только когда сервис прошел свой healthcheck (как раз блок condition)

• environment

  • тут мы указываем переменные окружения, которые нужны для работы nginx-proxy:

    • VIRTUAL_HOST название домена доступа к приложению

    • VIRTUAL_PORT порт, на котором запущено приложение в контейнере

    • LETSENCRYPT_HOST тот же самый домен но уже для создания https сертификата

    • LETSENCRYPT_EMAIL электронная почта, куда писать о том, что скоро сертификат будет просрочен

  • тут используется внешняя переменная окружения ${DOMAIN} и она будет записаться из файла .env который будет лежать рядом с docker-compose.yml файлом (подробнее тут).

Конечный вариант файла также находится в github репозитории.

Дополнительные моменты в подготовке окружения

В корне проекта я создал файл .dockerignore чтобы, во время сборки, не перекачивать в контекст лишнего:

#.dockerignore
.idea
.git
**/.nuxt
**/dist
**/.output
**/node_modules
**/.env

Также создал .env.example в качестве файла-примера:

DOMAIN=domain.ru

Запуск приложения

Подготовка сервера

Разумеется на сервере должен уже стоять Docker. Если нет, то установите его по официальной инструкции.

Далее необходимо на сервере запустить nginx-proxy и лучше это делать в отдельном месте на том-же сервере (инструкция здесь, но если нужно, то напишите в комментариях и дополню эту инструкцию здесь).

Запуск самого приложения

Запускается все это приложение очень простым образом:

1. Клонируем исходники

2. Прописываем DOMAIN в .env файл в корне проекта

3. Запускаем командой docker-compose up -d

Одной командой этот запуск можно сделать следующей командой:

DOMAIN=domain.ru && echo DOMAIN=$DOMAIN > .env && docker-compose up -d --build

Важно: заменить domain.ru на свой домен, который уже направлен на сервер, где мы запускаем сервис.

Обновление версии приложения

Если нужно обновить исходники до последней версии, то можно выполнить следующую команду:

git fetch && git reset --hard origin/master && docker-compose up -d --build

И проект обновится и запустит обновленную версию на домене.

Небольшое заключение

В конечном итоге получился вариант шаблона приложения на Nuxt + Nest который дальше можно расширять. Он крайне пуст — нет БД, авторизации и прочих базовых вещей. Разумеется в наших проектах есть разные шаблоны приложений, но я решил начать с описания самого базового варианта, который дальше можно развивать куда угодно.

Если подобный формат полезен и интересен для дальнейшего описания, то в следующих статьях опишу подобный стартовый набор с базой данных (Postgres) и авторизацией (JWT). Также есть мысль описать процесс подготовки и настройки ansible для подобных проектов.

Также в своем личном блоге в рубрике разработка пишу разные обучающие статьи и делюсь опытом на своем Youtube канале и Telegram.

Благодарю за внимание.