D-10: 배포 & 최적화 ② — 밖으로 내보냅니다

안녕하세요, 홍순구입니다.

시작하기 전에 명령 하나만 같이 돌려볼게요, 저장소 뿌리에서요.

ls node_modules | wc -l

564

우리가 설치한 꾸러미는 564개, 용량으로는 684MB인데, React 하나 Next 하나 깔았을 뿐인데도 그 안에서 딸려 온 것들까지 합쳐지면 이렇게 커집니다.

오늘은 이 앱을 컨테이너 하나에 담는데, 그 컨테이너 안에 실제로 들어가는 꾸러미는 열한 개뿐이에요.

564개에서 11개로 줄어드는 이 숫자가 어디서 갈리는지가 오늘 수업의 절반이고, 나머지 절반은 그 뒤에 옵니다.

담아서 띄웠는데 화면이 뜨긴 뜨는데 벌거벗어 있고, 그걸 고쳤더니 이번엔 피드가 영영 안 옵니다. 둘 다 응답은 200이라서, 지난 시간에 배운 그 문장이 오늘 두 번 더 나옵니다.

 지금 상태       내 노트북에서만 돈다
   │             node_modules 684MB · 꾸러미 564개
   ↓  output: 'standalone' 한 줄
 골라낸 덩어리   50MB · 꾸러미 12개
   │             그런데 띄우면 화면이 벌거벗는다
   ↓  Dockerfile 3단계
 컨테이너        222MB · 어디서든 명령 하나로 뜬다
   │             그런데 컨테이너 안에서 localhost 는 컨테이너 자신이다
   ↓  주소를 밖에서 받게
 완성            같은 이미지 하나 · 환경마다 다른 값

💡 오늘 수업의 핵심 — "실행에 필요한 것만 골라 담고, 환경마다 달라지는 값은 밖에서 받는다"

🎯 학습 목표

• output: 'standalone'이 무엇을 골라내고 무엇을 일부러 빼는지 알고, 빠진 것을 직접 채웁니다.
• 멀티스테이지 Dockerfile로 인스타그램 클론을 컨테이너 하나에 담아 실행합니다.
• 코드에 적어둔 값 중 밖으로 나가면 뜻이 달라지는 것을 찾아, 환경 변수로 분리합니다.

Step 1: "아직 제 노트북에서만 돕니다"

지금까지 우리가 앱을 띄운 방법은 둘 중 하나였습니다.

npx next dev     # 개발할 때
npx next start   # 빌드한 걸 확인할 때

next start는 프로덕션용 서버가 맞아서 진짜 서버에 그대로 올려도 돌아가는데, 그러려면 무엇을 들고 가야 할까요.

두 덩어리가 필요합니다

next start는 두 가지에 기대고 있는데, 하나는 빌드 결과인 .next 폴더고 다른 하나는 node_modules입니다. 둘 다 재봅시다.

du -sh node_modules
du -sh apps/web-next/.next

684M   node_modules
 71M   apps/web-next/.next

755MB 를 서버에 올려야 한다는 뜻인데, 여기서 두 가지가 걸려요.

첫째, node_modules는 올린다고 되는 게 아닙니다. 그 안에는 우리가 지금 쓰는 컴퓨터에 맞춰 설치된 것들이 섞여 있어서, 제 맥에서 만든 폴더를 리눅스 서버에 복사하면 어떤 꾸러미는 그대로 안 돌아가다 보니, 보통은 서버에서 npm install을 다시 돌리는데 그러면 서버에도 빌드 도구가 전부 깔려야 하죠.

둘째, 684MB 중에 실행에 진짜 필요한 것은 얼마나 될까요. typescript, eslint, tailwindcss는 빌드할 때 쓰는 도구라서 빌드가 끝난 뒤에는 한 번도 안 불리는데, 폴더에는 그대로 남아 있습니다.

.next 안도 마찬가지입니다

du -sh apps/web-next/.next/server apps/web-next/.next/static apps/web-next/.next/cache

 12M   .next/server
4.3M   .next/static
 54M   .next/cache

server는 서버가 화면을 그릴 때 읽는 것이고 static은 브라우저가 받아가는 JS·CSS·글꼴이라서, 둘 다 실행에 필요해요.

server·static과 달리 cache는 다음 빌드를 빠르게 하려고 두는 것이라 서버에서는 한 번도 안 읽히는데, .next의 절반을 넘게 차지하고 있어요. (이 숫자는 빌드를 몇 번 돌렸느냐에 따라 달라지는데, 제 노트북에서는 54MB 였다가 여러 번 돌린 뒤에는 62MB 까지 늘었어요.)

정리하면 이렇습니다.

들고 가야 할 것과 안 들고 가도 될 것이 섞여 있으니, 누가 이걸 대신 골라주면 좋겠는데요.

💡 한 줄 정리

next start는 node_modules와 .next 둘 다 필요한데, 그 안에는 빌드에만 쓰이고 실행에는 한 번도 안 읽히는 것이 섞여 있다.

Step 2: "담을 것만 골라냅니다"

next.config.ts에 한 줄을 더합니다.

// apps/web-next/next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // 실행에 진짜 필요한 것만 골라 한 덩어리로 내보낸다.
  output: 'standalone',
  typedRoutes: true,
  // 굳힐 것과 흘려보낼 것을 우리가 직접 고르겠다고 선언하는 스위치.
  cacheComponents: true,
  images: {
    // 여기 적힌 주소에서 온 사진만 다시 만들어 준다. 나머지는 400 으로 거절한다.
    remotePatterns: [new URL('https://picsum.photos/seed/**')],
  },
};

export default nextConfig;

다시 빌드합니다.

rm -rf .next
npx next build

화면이 달라진 게 아니라서 라우트 표는 지난 시간과 한 글자도 안 다른데, 대신 폴더가 하나 생겼습니다.

du -sh apps/web-next/.next/standalone
ls apps/web-next/.next/standalone/node_modules | wc -l

50M
12

684MB 에서 50MB, 564개에서 12개로 줄었는데, import와 require를 하나씩 따라가면서 Next가 우리 코드를 훑어 "이건 실행할 때 실제로 불린다"를 따라간 결과입니다.

무엇이 살아남았는지 직접 봅시다.

ls apps/web-next/.next/standalone/node_modules

@emnapi  @img  @next  @swc  client-only  detect-libc
next  react  react-dom  semver  sharp  styled-jsx

typescript도 eslint도 tailwindcss도 없는데, Tailwind는 빌드할 때 CSS 파일을 만들고 나면 할 일이 끝나기 때문이고, 만들어진 CSS는 static에 이미 들어 있습니다.

sharp는 남았는데, 지난 시간에 사진 크기를 줄이고 형식을 바꿔주던 그 도구라 요청이 올 때마다 실제로 일하니까 실행에 필요하죠.

우리 server.js는 한 겹 안쪽에 있습니다

폴더 구조를 봅시다.

find apps/web-next/.next/standalone -maxdepth 3 -not -path '*/node_modules/*'

.next/standalone/
.next/standalone/node_modules/
.next/standalone/apps/
.next/standalone/apps/web-next/
.next/standalone/apps/web-next/.next/
.next/standalone/apps/web-next/package.json
.next/standalone/apps/web-next/server.js

공식 문서나 블로그 예제를 보면 node server.js로 띄우라고 하는데, 우리 것은 뿌리에 server.js가 없고 apps/web-next/ 안쪽에 있습니다.

우리 저장소가 한 뿌리에 여러 앱을 담고 apps/web-spa와 apps/web-next가 node_modules를 같이 쓰고 있다 보니, Next가 그 구조를 그대로 복제해서 실행 명령이 이렇게 됩니다.

node .next/standalone/apps/web-next/server.js

이 한 줄을 못 찾아서 헤매는 경우가 꽤 많은데, 예제를 그대로 베끼면 "그런 파일 없다"는 소리만 듣거든요. 베끼기 전에 find로 어디 있는지 한 번 보는 게 빠릅니다.

💡 한 줄 정리

output: 'standalone'은 import를 따라가며 실행에 실제로 쓰이는 것만 골라 .next/standalone에 모은다. 우리 저장소는 앱이 여러 개라 server.js가 apps/web-next/ 안쪽에 생긴다.

const name = someCondition ? 'ko' : 'en';
const messages = await import(`./locales/${name}.json`);

Step 3: "띄웠는데 화면이 벌거벗었습니다"

골라냈으니 띄워봅시다. 개발 서버가 3000번을 쓰고 있을 테니 다른 번호를 줄게요.

PORT=3300 node .next/standalone/apps/web-next/server.js

▲ Next.js 16.3.1
- Local: http://localhost:3300
✓ Ready in 0ms

떴으니 브라우저로 열어봅니다.

curl -s -o /dev/null -b 'me=minji' -w "%{http_code} %{size_download}\n" http://localhost:3300/

200 25499

200이고 HTML도 25KB 나 왔는데, 브라우저에서 보면 이렇게 생겼습니다.

글자만 세로로 주르륵 쌓여 있고 배경도 흰색, 글꼴도 기본 글꼴이라 하트 버튼은 눌러도 아무 일이 없는데, 지난 시간에 그렇게 공들여 붙인 글꼴이 사라져 있습니다.

무엇이 안 왔는지 세어보는데, HTML 안에서 브라우저가 받아가야 할 주소를 뽑아서 하나씩 불러보는 거예요.

curl -s -b 'me=minji' http://localhost:3300/ \
  | grep -o '/_next/static/[^"]*' | sort -u \
  | while read u; do
      echo "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:3300$u)  $u"
    done

404  /_next/static/chunks/0ay527mnq1105.js
404  /_next/static/chunks/0cz1d0mv5g_q7.js
404  /_next/static/chunks/2a9batolpjr0x.css
...
404  /_next/static/chunks/turbopack-2hdzkb-n4145y.js
404  /_next/static/media/fca78c2ee6cec166-s.p.1sn26-iqxrgtp.woff2

11개 전부 404인데, JS 아홉 개, CSS 하나, 글꼴 하나요.

페이지는 200 인데 그 페이지가 부르는 것이 전부 없다 보니, 브라우저는 시키는 대로 받으러 갔다가 전부 빈손으로 돌아와서 스타일이 없고, 글꼴이 없고, 버튼이 안 눌립니다.

일부러 뺀 것입니다

버그가 아니라 공식 문서가 이렇게 적어뒀어요.

This minimal server does not copy the public or .next/static folders by default as these should ideally be handled by a CDN instead.

static은 요청이 올 때마다 서버가 계산해서 만드는 게 아니라 한 번 만들어두면 안 바뀌는 파일들이라서, 전 세계에 복사본을 뿌려두는 별도 서비스가 대신 나눠주는 편이 빠르다는 뜻이라 기본으로는 안 담습니다.

우리는 그런 서비스를 안 쓰니까 직접 넣어줍니다.

cp -r apps/web-next/.next/static apps/web-next/.next/standalone/apps/web-next/.next/static

복사했으니 다시 불러볼까요.

404  /_next/static/chunks/2a9batolpjr0x.css
404  /_next/static/media/fca78c2ee6cec166-s.p.1sn26-iqxrgtp.woff2

파일은 분명히 거기 있는데도 여전히 404입니다.

서버가 부팅할 때 "내가 나눠줄 수 있는 정적 파일 목록"을 한 번 읽고 기억해두기 때문에 서버를 껐다 켜면 그때 200이 되는데, 그 뒤에 폴더에 파일을 넣어도 목록에는 안 들어갑니다.

# 서버를 끄고 다시
PORT=3300 node .next/standalone/apps/web-next/server.js

11개 → 200 이 11개

이제 화면이 제대로 나옵니다. 배경색도, 글꼴도, 하트 버튼도요.

💡 한 줄 정리

standalone은 .next/static과 public을 일부러 안 담는다. 안 담긴 상태로 띄우면 페이지는 200 인데 그 페이지가 부르는 파일이 전부 404 다. 복사한 뒤에는 반드시 서버를 다시 띄워야 한다.

Step 4: "컨테이너 하나에 담습니다"

50MB 짜리 덩어리를 만들었고 빠진 것도 채웠는데, 이걸 서버에 올려도 아직 문제가 남아요.

그 서버에는 Node.js가, 그것도 우리와 같은 버전으로 깔려 있어야 하는데, 버전이 다르면 어떤 문법은 돌고 어떤 문법은 안 되다 보니 팀에 새로 온 사람이 자기 노트북에서 띄우려 해도 같은 이야기가 반복돼요.

컨테이너는 이걸 통째로 묶는 방법인데, 우리 앱만 담는 게 아니라 리눅스 한 조각과 Node.js까지 같이 담다 보니 그걸 받은 사람은 자기 컴퓨터에 Node가 몇 버전이든 상관없이 명령 하나로 띄웁니다.

무엇을 어떻게 담을지는 Dockerfile이라는 파일에 적습니다.

세 단계로 나눕니다

# apps/web-next/Dockerfile

# 1단계 — 설치. 여기서만 npm 을 쓴다.
FROM node:24-alpine AS deps
WORKDIR /repo
COPY package.json package-lock.json ./
COPY apps/web-next/package.json apps/web-next/
RUN npm ci --workspace web-next --include-workspace-root

# 2단계 — 빌드. 소스를 넣고 next build 를 돌린다.
FROM node:24-alpine AS builder
WORKDIR /repo
COPY --from=deps /repo/node_modules ./node_modules
COPY . .
WORKDIR /repo/apps/web-next
RUN npx next build

# 3단계 — 실행. 앞 두 단계에서 만든 결과만 가져온다. 소스도 개발 도구도 안 따라온다.
FROM node:24-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /repo/apps/web-next/.next/standalone ./
COPY --from=builder /repo/apps/web-next/.next/static ./apps/web-next/.next/static
EXPOSE 3000
CMD ["node", "apps/web-next/server.js"]

FROM이 세 번 나오는데, 각각이 별도의 작업 공간입니다. 그리고 마지막 FROM만 실제 결과물이 됩니다. 앞의 둘은 재료를 만드는 데만 쓰이고 버려져요.

COPY --from=builder가 그 다리인데, "버려질 2단계에서 이것만 꺼내 와라"는 뜻이에요.

여기서 Step 3의 교훈이 그대로 반영돼 있어서, standalone을 복사하는 줄 바로 밑에 static을 복사하는 줄이 따로 있죠. 저 한 줄이 없으면 컨테이너를 띄울 때마다 벌거벗은 화면을 보게 됩니다.

 1단계 deps      npm ci 로 꾸러미를 받는다
                   │ node_modules
                   ↓
 2단계 builder   소스를 넣고 next build
                   │ .next/standalone · .next/static
                   ↓
 3단계 runner    받아온 결과만 있다 ← 이것만 이미지가 된다

저장소 뿌리에는 안 담을 것 목록도 하나 둡니다.

node_modules
**/node_modules
**/.next
**/scratch
.git

이걸 안 두면 1단계에서 새로 받을 건데도 우리 노트북의 684MB 짜리 node_modules가 통째로 컨테이너 안으로 복사되는데, .git도 마찬가지고요.

만들어봅시다

docker build -f apps/web-next/Dockerfile -t insta-next:d10 .

맨 끝의 점이 중요한데, "어느 폴더를 재료로 쓸 거냐"를 가리키는 것이니 저장소 뿌리를 줘야 해요. package-lock.json이 거기 있고 두 앱이 node_modules를 나눠 쓰니까요.

#18 exporting to image
#18 naming to docker.io/library/insta-next:d10 done

docker build ...  57.272 total

57초 걸렸고 종료 코드는 0입니다. 크기를 봅시다.

docker images insta-next:d10

REPOSITORY   TAG   SIZE
insta-next   d10   222MB

안에 뭐가 들었나 열어봅시다

docker run -d --name insta-d10 -p 3400:3000 insta-next:d10
docker exec insta-d10 sh -c 'ls /app/node_modules; find /app/apps -name "*.ts*" | wc -l'

@img  @next  @swc  client-only  detect-libc
next  react  react-dom  semver  sharp  styled-jsx
0

꾸러미 11개, 소스 파일 0개인데, 우리가 쓴 .tsx 파일은 한 개도 안 들어갔습니다. 이미 JS로 변환돼서 .next 안에 들어가 있으니까요.

(제 노트북의 standalone은 12개였는데 컨테이너 안은 11개인 것은 sharp가 운영체제마다 다른 조각을 딸려 오기 때문이라, 여러분 화면의 숫자가 하나쯤 달라도 정상이에요.)

한 가지 더 짚고 갈 게 있습니다. 이 빌드는 백엔드 API 서버가 안 떠 있는 상태에서 돌았는데, 컨테이너 안에서는 우리 스텁 서버에 닿을 방법이 아예 없는데도 종료 코드는 0 이었어요.

지난 시간들에 우리가 캐시를 손보면서 화면에 필요한 데이터를 미리 받아두는 대신 요청이 올 때 받아오도록 바꿔뒀기 때문에, 빌드하는 기계는 API 서버를 몰라도 되는데, 배포 관점에서 이건 꽤 큰 이야기예요.

💡 한 줄 정리

멀티스테이지 Dockerfile은 설치·빌드·실행을 갈라, 마지막 단계에 앞 단계의 결과만 가져온다. 완성된 이미지 222MB 안에는 꾸러미 11개가 있고 우리 소스 파일은 0개다.

docker history insta-next:d10

4.24MB   COPY .next/static ...
55.7MB   COPY .next/standalone ...

Step 5: "컨테이너 안에서 localhost는 자기 자신입니다"

컨테이너가 떴으니 3400번으로 열어봅시다.

curl -s -o /dev/null -b 'me=minji' -w "%{http_code} %{size_download}\n" http://localhost:3400/

200 10680

또 200이고, 화면을 보면 머리말은 제대로 나오고 글꼴도 맞고 색도 맞아서 Step 3의 그 문제는 아니지만, 피드 자리에는 이 글자가 떠 있고 영영 안 바뀝니다.

피드를 불러오는 중…

컨테이너 로그를 봅시다.

docker logs insta-d10

⨯ [TypeError: fetch failed] {
  [cause]: AggregateError:
    code: 'ECONNREFUSED',

연결을 거부당했습니다. 어디에 연결하려다가요? 우리가 코드에 적어둔 그 주소죠.

const API_BASE = 'http://localhost:8090/api';

오늘의 함정이 여기 있는데, localhost는 "이 컴퓨터"라는 뜻이라 제 노트북에서 돌 때는 제 노트북이었지만, 컨테이너 안에서 도는 코드에게 "이 컴퓨터"는 컨테이너 자신이라서 8090번에서 듣고 있는 게 아무것도 없고요.

같은 글자가 실행되는 곳에 따라 다른 곳을 가리켜서, 옮기기 전에는 알 수가 없어요.

한 원인이 네 가지 얼굴로 나타납니다

주소가 틀렸다는 원인은 하나인데, 화면마다 다르게 드러납니다. 전부 재봤어요.

세 번째 줄을 보면 D-7에서 405밀리초를 주고 되찾았던 404가 500이 됐는데, 없는 사람을 알아보려면 API에 물어봐야 하다가 터지니까요.

네 번째 줄은 멀쩡합니다. 그런데 로그아웃한 사람은 여전히 307로 돌려보내져요.

이게 왜 갈릴까요. D-8에서 문지기의 검사 순서를 정할 때 우리는 쿠키 확인을 API 요청보다 앞에 뒀는데, 그때는 네트워크를 타기 전에 끝나는 검사가 제일 싸다는 속도 때문이었어요.

그 순서가 지금 다른 값을 하는데, API 서버가 통째로 죽어도 로그인 안 한 사람은 여전히 못 들어오고, 뒤에 뒀으면 서버가 죽는 순간 문이 열렸을 거예요.

성능을 위해 고른 순서가 서버 장애 상황에서 보안을 지켜준 셈이라, 이런 건 설계할 때 다 내다보고 고르기 어렵지만, 싼 검사를 앞에 두는 습관이 이런 이득을 자주 데려옵니다.

💡 한 줄 정리

localhost는 실행되는 곳을 따라간다. 컨테이너 안에서는 컨테이너 자신을 가리켜서, 같은 원인이 200·500·307로 서로 다르게 드러난다.

Step 6: "주소를 밖에서 받습니다"

고치기 전에 먼저 세어봅시다. 그 주소가 코드에 몇 번 적혀 있을까요.

grep -rn "localhost:8090" apps/web-next --include="*.ts"

apps/web-next/lib/api.ts:7:const API_BASE = 'http://localhost:8090/api';
apps/web-next/proxy.ts:5:const API_BASE = 'http://localhost:8090/api';

두 군데인데, 하나만 고치면 절반만 고쳐져요.

실제로 그런 일이 벌어지는데, api.ts만 고치고 띄우면 피드는 정상으로 나오는데 프로필 화면은 여전히 500이에요. 화면 하나가 되니까 다 된 줄 알고 넘어가기 딱 좋습니다.

한 곳으로 모읍니다

새 파일을 하나 만듭니다.

// apps/web-next/lib/config.ts

// 백엔드 주소는 실행하는 곳마다 다르다.
// 내 노트북에서는 localhost 지만, 컨테이너 안에서 localhost 는 컨테이너 자신이다.
// 그래서 값을 코드에 적어두지 않고 밖에서 받는다 — 못 받으면 개발용 주소를 쓴다.
export const API_BASE = process.env.API_BASE ?? 'http://localhost:8090/api';

process.env는 앱을 실행시킬 때 밖에서 건네주는 값들이 담긴 곳인데, 없으면 ?? 뒤의 값을 쓰다 보니 개발할 때는 아무것도 안 줘도 지금까지처럼 돌아가라는 뜻이에요.

두 파일이 이 값을 읽게 바꿉니다.

// apps/web-next/lib/api.ts
import { cacheLife, cacheTag } from 'next/cache';
import type { Post } from './posts';
// 브라우저가 아니라 서버가 부른다. 서버에는 "지금 보고 있는 주소" 같은 게 없어서
// 상대 경로(/api/posts)로는 어디로 갈지 정할 수 없다 — 주소를 통째로 적는다.
// 그 주소를 어디서 받아오는지는 config.ts 한 곳에서 정한다.
import { API_BASE } from './config';

// apps/web-next/proxy.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { API_BASE } from './lib/config';

두 파일 모두 const 선언이 사라지고 import 한 줄로 바뀌면서, 이제 주소가 코드에 한 번만 적혀 있는데, 그 한 번도 "못 받았을 때 쓸 값" 이지 진짜 주소가 아닙니다.

같은 이미지, 다른 값

이미지를 다시 만들고 이번엔 값을 주면서 띄웁니다.

docker build -f apps/web-next/Dockerfile -t insta-next:d10 .
docker run -d --name insta-d10 -p 3400:3000 \
  -e API_BASE=http://host.docker.internal:8090/api \
  insta-next:d10

-e가 그 값을 건네는 부분입니다.

로그인 후 /          200  (0.42s)   피드 정상
로그인 후 /explore   200  (0.01s)
로그인 후 /jaehoon   200  (1.64s)
로그인 후 /zzzzz     404  (0.42s)
로그아웃  /jaehoon   307

전부 돌아왔습니다.

여기서 중요한 건 이미지를 안 바꿨다는 것인데, 방금 만든 그 이미지 하나로 값을 안 주면 안 되던 것이 값을 주니까 됐어요.

이 성질이 실무에서 크게 쓰이는데, 개발용·테스트용·진짜 서비스용 이미지를 따로 만들지 않고 하나를 만들어서 값만 바꿔가며 단계마다 올립니다. 테스트에서 확인한 것과 서비스에 올라간 것이 글자 하나까지 같은 물건이라는 뜻이니까요.

💡 한 줄 정리

실행되는 곳마다 달라지는 값은 코드에 적지 않고 밖에서 받는다. 그러면 이미지 하나로 환경마다 다르게 띄울 수 있고, 단계마다 똑같은 물건을 올릴 수 있다.

NEXT_PUBLIC_PROBE="빌드때값" npx next build
NEXT_PUBLIC_PROBE="실행때값" node .next/standalone/apps/web-next/server.js

Step 7: "앞 회차가 산 것이 여기서도 삽니까"

컨테이너가 잘 뜬다는 건 확인했는데, 우리가 지난 회차들에서 시간과 성능을 주고 산 것들이 있어서 그것들이 컨테이너 안에서도 살아 있는지는 따로 확인해야 합니다.

옮기는 작업은 조용히 무언가를 떨어뜨리기 쉬운데, 화면이 뜨니까 다 된 것 같아도 실은 하나가 죽어 있는 식이에요. Step 5에서 404가 500으로 바뀐 걸 이미 봤죠.

하나씩 재봅니다.

404

curl -s -o /dev/null -b 'me=minji' -w "%{http_code}\n" http://localhost:3400/zzzzz

404

살아 있는데, 이건 D-7에서 첫 바이트를 2밀리초에서 405밀리초로 늦추면서까지 되찾은 것이었고, 컨테이너 안에서도 그 값을 그대로 치르고 그대로 얻습니다.

문지기

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3400/jaehoon

307

쿠키 없이 남의 프로필을 열려고 하면 여전히 돌려보내집니다.

사진

curl -s -o /dev/null -b 'me=minji' \
  -w "%{http_code} %{content_type} %{size_download}\n" \
  "http://localhost:3400/_next/image?url=https%3A%2F%2Fpicsum.photos%2Fseed%2Fpost1%2F640%2F640&w=384&q=75"

200 image/jpeg 24644

원본이 74KB 였던 사진이 24KB 로 줄어서 오는 건 sharp가 컨테이너 안에 함께 담겼기 때문이에요. Step 2에서 열두 개 목록에 그 이름이 있는 걸 봤죠. 저게 안 담겼으면 이 요청이 실패했을 겁니다.

글꼴

docker exec insta-d10 find /app -name "*.woff2" | head -3

/app/apps/web-next/.next/static/media/e46336d0fe4d243f-s.1ihe76kx1l647.woff2
/app/apps/web-next/.next/static/media/2ea9328f7c652dae-s.2_zjfs_06xy5e.woff2
/app/apps/web-next/.next/static/media/5882eb9fe44d78e2-s.2zlo_5j6rno3q.woff2

글꼴 파일이 컨테이너 안에 들어 있는 건, 지난 시간에 글꼴을 우리 서버가 직접 나눠주도록 바꿔뒀기 때문이라 컨테이너는 인터넷이 끊겨도 글꼴을 줄 수 있어요.

주소마다 다른 제목

curl -s -b 'me=minji' http://localhost:3400/minji | grep -o '<title>[^<]*</title>'

<title>@minji · 인스타그램 클론</title>

이것도 살아 있습니다.

전부 모아보면

전부 무손상입니다. 다만 이건 당연한 게 아니라 확인한 결과예요. Step 5에서 봤듯이 설정 하나가 틀리면 이 표의 첫 줄이 조용히 죽어 있을 수 있습니다.

💡 한 줄 정리

옮기고 나면 앞에서 얻어둔 것들이 그대로인지 따로 확인한다. 화면이 뜨는 것과 전부 살아 있는 것은 다른 이야기다.

Step 8: "남이 대신 해주는 것과 그 대가"

오늘 우리가 한 일을 되짚어봅시다.

설정 한 줄을 넣고, 빠진 폴더를 복사하고, Dockerfile을 세 단계로 쓰고, 컨테이너를 띄우고, 주소를 밖으로 빼고, 다섯 가지를 다시 확인했는데, 대략 여기까지가 직접 굴린다는 것의 내용이에요.

이 과정을 통째로 안 해도 되는 방법도 있습니다. 그런데 Next.js를 만든 회사인 Vercel에 저장소를 연결하면 코드를 올릴 때마다 알아서 빌드하고 알아서 띄워줘서 설정 파일을 하나도 안 써도 돼요. 흔히 zero-config라고 부릅니다.

우리가 오늘 손으로 한 것들이 거기서는 이렇게 됩니다.

그런데 이건 마법이 아니었습니다

여기가 최근에 바뀐 부분이라 짚고 갑니다.

예전에는 Vercel이 Next 앱을 어떻게 빌드해서 어떻게 띄우는지가 밖에서 안 보였습니다. Next 안쪽에 문서화되지 않은 통로가 있었고 그 통로를 쓰는 코드가 공개돼 있지 않아서, "다른 곳에 올리면 어떤 기능이 안 될까"를 미리 알기 어려웠습니다.

Next 16부터 그 통로가 어댑터라는 이름으로 정식 공개되면서, 어떤 회사든 자기 서비스에 맞는 어댑터를 만들어 붙일 수 있고 Vercel 자신도 이제 그 공개된 통로를 쓰는 어댑터로 동작합니다.

공식 문서는 어댑터 중 검증된 것을 따로 표시하는데, 소스가 공개돼 있고 Next 팀이 만든 시험을 전부 통과했고 주요 버전이 나오기 전에 함께 시험을 돌린 것들이에요. 지금 이 목록에 있는 건 Vercel과 Bun 두 곳이고, Cloudflare와 Netlify는 작업 중이고요.

학생 입장에서 이게 왜 중요할까요. "어디에 올릴지"가 되돌리기 어려운 결정이 아니게 됐다는 뜻이라서인데, 예전에는 한 곳에 맞춰 만들면 옮길 때 상당 부분을 다시 손봐야 했습니다.

그래도 값은 있습니다

맡기면 편한 대신 내는 것이 있어요.

돈. 방문자가 늘면 청구서가 따라 느는데, 우리 컨테이너는 서버 한 대 값만 내면 그 위에서 얼마가 오든 같은 값이에요.

갈 수 있는 곳. 회사에 따라 데이터가 자기 나라 밖으로 나가면 안 되거나 아예 인터넷과 끊긴 곳에서만 돌려야 하는 경우가 있는데, 이럴 때는 선택지가 없어요.

옆에 있는 것들. 데이터베이스나 백엔드 API가 이미 회사 서버에 있으면 화면만 밖에 두는 게 오히려 복잡해지는데, 우리 백엔드가 그렇죠.

그래서 어떻게 고르나

🌟 개인 프로젝트·포트폴리오·빠르게 확인할 것 → 맡깁니다. 오늘 배운 걸 하나도 안 쓰고 5분이면 세상에 나가요.

회사 서비스·백엔드가 이미 어딘가에 있는 경우·규제가 있는 경우 → 컨테이너를 직접 굴립니다. 오늘 만든 것이 그 출발점이에요.

중요한 건 오늘 배운 것이 어느 쪽을 골라도 안 버려진다는 점인데, 맡기더라도 무슨 일이 대신 벌어지고 있는지 알게 됐으니까요. 배포가 실패했을 때 로그를 읽을 수 있는 사람과 못 읽는 사람의 차이가 거기서 갈립니다.

💡 한 줄 정리

맡기는 방식은 오늘 한 일을 대신 해주는 것이지 없애주는 것이 아니다. Next 16부터 그 과정이 어댑터로 공개돼서, 어디에 올릴지가 되돌리기 어려운 결정은 아니게 됐다.

마무리

오늘 배운 핵심 세 가지

💡 하나 — 실행에 필요한 것만 골라 담습니다. 우리가 설치한 564개 중 실제로 실행에 쓰이는 건 열두어 개였습니다. 684MB 가 50MB 가 됐고, 컨테이너로는 222MB 가 됐어요. 골라내는 기준은 import를 따라가는 것이고, 그래서 이름을 변수로 조립해 부르는 코드는 못 따라갑니다.

💡 둘 — 200은 오늘 두 번 더 거짓말을 했습니다. 한 번은 정적 파일이 안 담겨서 페이지만 200이고 그 안의 열한 개가 전부 404 일 때, 또 한 번은 컨테이너 안에서 백엔드에 못 닿아 피드가 영영 안 올 때요. 둘 다 응답 상태로는 멀쩡해 보였습니다. 하지만 만든 것은 띄워서 화면까지 봐야 합니다.

💡 셋 — 실행되는 곳마다 달라지는 값은 코드에 적지 않습니다. localhost는 옮기는 순간 다른 곳을 가리켰고, 게다가 두 파일에 따로 적혀 있어서 하나만 고치면 절반만 고쳐졌어요. 한 곳으로 모으고 밖에서 받게 하면, 이미지 하나로 환경마다 다르게 띄울 수 있습니다.

다음 시간 예고

여기까지가 Next.js입니다. 폴더로 주소를 만드는 것부터 시작해서, 서버와 브라우저의 경계를 긋고, 무엇을 굳히고 무엇을 흘려보낼지 정하고, 요청을 받고, 사진과 글꼴을 붙이고, 오늘 컨테이너에 담아 밖으로 내보냈어요.

우리가 지금까지 무언가를 고칠 때마다 무슨 일을 했는지 떠올려보면, 매번 손으로 확인했습니다. 화면을 열어보고, curl을 날려보고, 숫자를 세어봤죠. Step 7에서도 다섯 줄을 손으로 확인했고요.

앱이 커지면 이게 안 되는데, 좋아요 버튼 하나를 고쳤는데 그것 때문에 댓글 삭제가 망가졌는지를 매번 손으로 다 눌러볼 수는 없어요.

다음 시간부터는 그 확인을 코드로 적습니다. 우리 대신 앱을 눌러보고 결과를 비교해주는 코드를요.

무대도 잠깐 바뀝니다. 브라우저에서만 도는 앱으로 돌아가요. 다만 다음 시간에 우리가 처음 할 일은 그런 코드를 쓰는 게 아니라 이 저장소를 열어서 그런 코드가 이미 몇 개나 있는지 세어보는 것부터예요. 직접 쓰기 시작하는 건 그다음 시간이고요.

과제

[구현] static을 안 담고 컨테이너를 띄워보세요

Step 4의 Dockerfile에서 .next/static을 복사하는 줄을 지우고 이미지를 다시 만든 뒤, 띄워서 확인합니다.

1. 페이지 응답 상태는 몇인가요.
2. HTML 안의 /_next/static/... 주소들은 몇 개고 각각 몇 번을 돌려주나요.
3. 브라우저로 열었을 때 화면이 어떻게 보이나요. 지난 시간에 붙인 글꼴은 어떻게 됐나요.

확인한 뒤 줄을 되돌리고 다시 만들어 정상으로 돌아오는 것까지 보세요.

이 과제의 목적은 일부러 깨뜨려서 증상을 외워두는 것인데, 나중에 실무에서 "화면이 벌거벗었다"를 만나면 3초 만에 원인을 떠올릴 수 있게요.

[구현] 주소를 한 군데만 고쳐보세요

lib/config.ts를 만들기 전 상태로 돌아가서, lib/api.ts만 환경 변수를 읽게 고치세요. proxy.ts는 그대로 두고요.

그 상태로 이미지를 만들고 -e API_BASE=...를 주며 띄운 뒤, 아래 네 가지를 확인하세요.

답해보세요. 피드 화면만 열어보고 "고쳤다" 고 결론 냈다면 무엇을 놓쳤을까요. 이런 종류의 절반짜리 수정을 배포 전에 잡으려면 무엇을 확인해야 할까요.

[탐구] NEXT_PUBLIC_ 값이 어디에 박히는지 직접 찾으세요

클라이언트 컴포넌트 하나를 골라 process.env.NEXT_PUBLIC_PROBE를 화면에 찍게 만든 뒤, 빌드할 때와 띄울 때 서로 다른 값을 주고 무엇이 화면에 뜨는지 확인합니다.

그다음이 진짜 과제인데, 빌드할 때 준 그 값이 어느 파일 안에 들어 있는지 찾아보세요.

grep -rl "빌드할때준값" apps/web-next/.next/static

찾았으면 그 파일이 브라우저에 어떻게 전달되는지, 그리고 방문자가 그것을 열어볼 수 있는지 생각해보세요.

확인한 뒤에는 찍는 코드를 지우고 원래대로 돌려놓습니다.

[탐구] 안 담을 것 목록을 비우면 어떻게 되나요

.dockerignore의 내용을 전부 지우고(파일은 남겨두고 빈 채로) 이미지를 다시 만드세요. 두 번 다 --no-cache --progress=plain을 붙이면 숫자가 잘 보입니다.

1. transferring context로 출력되는 재료 크기가 얼마나 달라지나요.
2. 빌드에 걸리는 시간은요.
3. 완성된 이미지 크기는 달라졌나요.

3번이 이 과제의 본체인데, 달라졌다면 무엇이 늘었는지 컨테이너 안을 열어서 찾아내세요.

docker run --rm --entrypoint sh insta-next:비운쪽 -c 'du -sh /app/*'
docker run --rm --entrypoint sh insta-next:비운쪽 -c 'du -sh /app/node_modules/* | sort -h | tail -4'

가장 커진 폴더를 찾았으면 그 안을 한 번 더 열어보고, 거기 있는 것들의 이름을 소리 내어 읽어보세요. Step 1에서 이야기한 문제가 눈앞에 있을 겁니다.

생각해볼 주제

1. 빌드하는 기계는 백엔드를 몰라도 되는가

Step 4에서 우리 컨테이너 빌드는 백엔드 API 서버 없이 성공했는데, 앞선 회차들에서 데이터를 요청이 올 때 받아오도록 바꿔둔 결과였어요.

만약 반대로, 빌드할 때 API를 불러서 화면을 미리 만들어두는 구조라면 어떨까요. 빌드하는 기계가 백엔드에 닿을 수 있어야 하고, 그 순간 백엔드가 살아 있어야 합니다. 대신 방문자는 이미 만들어진 화면을 즉시 받아요.

두 방식은 무엇을 얻고 무엇을 잃으며, 우리 인스타그램 클론의 각 화면(피드·탐색·프로필)에는 어느 쪽이 맞을까요.

2. 이미지 하나를 여러 환경에 올린다는 원칙

Step 6에서 "이미지 하나를 만들어 값만 바꿔가며 단계마다 올린다" 고 했는데, 테스트에서 확인한 것과 서비스에 올라간 것이 같은 물건이어야 하니까요.

NEXT_PUBLIC_ 값은 빌드할 때 박히는데, 만약 테스트 환경과 서비스 환경에서 브라우저가 부를 주소가 서로 달라야 한다면 이 원칙이 깨집니다.

이 상황을 어떻게 풀 수 있을지, 애초에 브라우저가 백엔드 주소를 알아야 하는 상황을 안 만들 수는 없을지 생각해보고, 지금 우리 앱이 그 주소를 브라우저에 안 넘기고 있는 이유를 떠올려보세요.

3. 되돌릴 수 있는 결정과 되돌리기 어려운 결정

Step 8에서 Next 16의 어댑터 이야기를 했는데, 예전에는 한 서비스에 맞춰 만들면 옮길 때 상당 부분을 다시 손봐야 했지만 이제는 그 통로가 공개돼서 옮기기가 전보다 수월해졌어요.

이걸 조금 더 넓혀 생각해보면, 개발하면서 내리는 결정 중에는 나중에 쉽게 바꿀 수 있는 것과 한 번 정하면 되돌리는 데 몇 달이 걸리는 것이 섞여 있습니다.

지금까지 이 과목에서 우리가 내린 결정들을 떠올려보고, 어느 것이 쉽게 되돌릴 수 있는 결정이었고 어느 것이 그렇지 않았는지, 되돌리기 어려운 결정 앞에서는 무엇을 다르게 해야 할지 생각해보세요.