Next를 16.3.4로 업그레이드하고, Docker 리소스 제한을 추가하며, VS 모노레포에 콘도 편의시설 엔드포인트를 배포하기

요약: 루트 Next.js 버전을 16.2.6에서 16.3.4로 올렸습니다. 이는 Vercel 미리보기 빌드를 수정하기 위함이며, docker-compose에 서비스별 CPU/RAM 제한을 도입했고, 콘도 편의시설(condo-amenities), 패키지, 결제 API 전체 세트를 추가했습니다. 변경 사항은 몇 개의 파일에 국한되지만, 신중한 버전 정렬과 컨테이너 튜닝이 필요했습니다.

문제점

1. Vercel 미리보기 실패 – Vercel은 모노레포의 루트 next 의존성이 16.2.6에 고정되어 있기 때문에 빌드를 거부하기 시작했습니다. 반면, Vercel 플랫폼은 이미 16.3.x로 업그레이드된 상태였습니다. 미리보기 로그에는 다음이 표시되었습니다:

   Error: Cannot find module 'next/dist/compiled/webpack'
   Require stack:
   - node_modules/next/dist/next-server.js

1. Docker 컨테이너 메모리 부족 – 로컬 통합 테스트 중 Postgres 컨테이너가 OOM(Out Of Memory)으로 종료되었고, 호스트에 제한이 정의되어 있지 않아 Gotenberg PDF 서비스가 간헐적으로 멈추는 현상이 있었습니다.

2. 콘도 편의시설 API 누락 – 제품 로드맵은 편의시설 예약 목록화, 생성 및 삭제를 위한 엔드포인트를 요구했지만, API 계층에는 결제(billing)와 웹훅(webhook) 컨트롤러만 존재했습니다. 이 기능이 없자 프런트엔드 페이지( /condominios/amenidades)가 404 오류를 반환했습니다.

제가 처음 시도한 것

Vercel 배포 및 리소스 관리 문제 해결 과정

• 오래된 Node 버전으로 Vercel 고정(Pinning) – Next 버전 불일치를 무시하기 위해 Vercel 대시보드에 NODE_VERSION=18을 설정했습니다. 하지만 작동하지 않았습니다. Vercel은 여전히 내부 Next 런타임을 사용했고, 빌드는 이전과 똑같이 실패했습니다.

• DB 서비스에만 mem_limit 추가 – docker-compose.yml 파일을 수정하여 db에만 mem_limit: 512m을 설정했지만 Gotenberg 서비스는 건드리지 않았습니다. DB가 OOM-killing(Out Of Memory killing)을 중단시켰지만, Gotenberg는 여전히 1GB 이상의 RAM을 소비하여 호스트가 스왑(swap)하게 만들었고 모든 테스트 속도를 늦췄습니다.

• apps/web에 임시 "편의 시설" 목(mock) 컨트롤러 생성 – 정적 JSON 파일을 추가하고 페이지 컴포넌트에서 이를 가져왔습니다. UI는 렌더링되었지만, API 계약(API contract)이 누락되어 백엔드 통합 테스트(integration tests)로 실행할 수 없었습니다.

위의 세 가지 시도는 부분적인 완화만 제공했을 뿐, 핵심 문제는 해결하지 못했습니다. 저는 적절한 버전 업그레이드, 전체적인 리소스 제한 전략, 그리고 실제 NestJS 컨트롤러가 필요했습니다.

구현 과정 (The Implementation)

1. Vercel 프리뷰를 위해 Next.js 버전 정렬

필요했던 변경 사항은 package.json 파일의 단 한 줄이었습니다. 저는 PR(\#14)을 열고 이전 버전을 교체했습니다:

@@ -21,7 +21,7 @@
   "dependencies": {
     "@notionhq/client": "^5.13.0",
...

버전 업그레이드 후 로컬에서 npm install을 실행하고, lockfile을 커밋한 뒤 푸시했습니다. 이제 Vercel은 런타임 버전이 패키지 버전을 일치시키면서 프리뷰를 성공적으로 빌드합니다.

2. 서비스별 CPU/RAM 제한 추가 및 Gotenberg 지연 로딩(lazy-load) 구현

저는 데이터베이스와 PDF 생성 서비스 모두에 제한을 설정하기 위해 docker-compose.yml (PR #13)을 수정했습니다:

@@ -1,6 +1,8 @@
 services:
   db:
...

Gotenberg가 필요하지 않을 때 실행되는 것을 방지하기 위해, 저는 apps/api/src/condo-fees/condo-autopay.cron.ts에 지연 로딩(lazy-load) 래퍼를 추가했습니다. 이제 크론 작업은 결제 배치(payment batch)가 처리될 때만 Docker API를 통해 임시 컨테이너를 구동합니다:

이 접근 방식은 개발 머신과 CI 러너의 유휴 RAM 사용량을 줄여줍니다.

3. condo-amenities REST API 구현

PR(#12)에서 추가된 가장 큰 부분은 전체 NestJS 컨트롤러, DTO 및 서비스 헬퍼입니다. 아래는 새 컨트롤러(apps/api/src/condo-amenities/condo-amenities.controller.ts)의 골격입니다:

// apps/api/src/condo-amenities/condo-amenities.controller.ts
import {
  Body, Controller, Delete, Get, HttpException,
...

또한 apps/api/src/app.module.ts에 컨트롤러를 등록했습니다:

@@ -46,6 +46,8 @@ import { MllController } from "./mll/mll.controller.js";
 import { NonDebtCertificatesController } from "./condo-fees/non-debt-certificates.controller.js";
 import { CondoAnnouncemen
...

프런트엔드 페이지(apps/web/src/app/condominios/amenidades/page.tsx)는 이제 /api/condo-amenities?condoId=123을 호출하고 JSON을 직접 렌더링하여 이전의 404 오류를 제거했습니다.

4. 사소한 변경 사항

저의 Build in Public 시리즈의 일부 — Playa del Carmen, México에서 Building PlayaMXCRM을 구축하는 실제 과정을 공유합니다.

레포: zaerohell/VS · 2026-10-07

#playadev #buildinpublic