Docker 컨테이너에서 Node.js 풀스택 앱 실행 시 흔한 문제 해결 가이드

Node.js와 React 기반의 풀스택 애플리케이션을 Docker 컨테이너에 배포할 때 마주칠 수 있는 흔한 문제들과 해결책을 정리했습니다. ERR_EMPTY_RESPONSE, ENOENT: no such file or directory, ReferenceError: __dirname is not defined와 같은 오류를 해결하는 데 도움이 될 것입니다.

1. ERR_EMPTY_RESPONSE 또는 ERR_CONNECTION_REFUSED

증상

• Docker 컨테이너를 실행하고 localhost:3000으로 접속했을 때 브라우저에서 연결 오류 발생
• Docker logs에서는 서버가 정상적으로 시작된 것처럼 보임
• 실제로는 외부에서 접근할 수 없는 상태

원인

Docker 컨테이너의 포트 매핑(-p 3000:3000)과 Node.js 애플리케이션이 실제로 리스닝하는 포트가 일치하지 않거나, 애플리케이션이 localhost (127.0.0.1)와 같이 컨테이너 내부에서만 접근 가능한 주소에서 리스닝하고 있기 때문입니다.

해결책

애플리케이션이 0.0.0.0 주소에서 리스닝하도록 수정하여 컨테이너 외부에서 접근 가능하게 만듭니다.

// server/index.ts
const port = parseInt(process.env.PORT || '3000', 10);

server.listen({
  port,
  host: "0.0.0.0", // 모든 네트워크 인터페이스에서 리스닝
}, () => {
  console.log(`Server running on port ${port}`);
});

 

2. ENOENT: no such file or directory

증상

ENOENT: no such file or directory, open '/app/dist/client/index.html'

컨테이너 로그에 위와 같은 오류가 발생하며, 서버가 빌드된 프론트엔드 파일 대신 개발 환경의 소스 파일을 찾으려고 시도합니다.

원인

Node.js 애플리케이션이 NODE_ENV=production 환경 변수를 제대로 인식하지 못하고 개발 모드로 실행되고 있기 때문입니다. 서버 진입점에서 환경 변수를 강제로 development로 설정하는 코드가 있을 수 있습니다.

해결책

서버 진입점에서 환경 변수를 강제로 설정하는 코드를 제거합니다.

// server/index.ts
const app = express();
// app.set('env', 'development'); // ❌ 이 줄을 제거하세요
app.use(express.json());

Dockerfile에서 환경 변수가 올바르게 설정되었는지 확인합니다:

ENV NODE_ENV=production

 

3. ReferenceError: __dirname is not defined

증상

ReferenceError: __dirname is not defined

ESM(ES Module) 환경에서 __dirname 사용 시 발생하는 오류입니다.

원인

package.json에 "type": "module"이 설정되어 있을 때, __dirname과 같은 CommonJS 전역 변수를 사용할 수 없습니다.

해결책

ESM 환경에서 __dirname을 사용할 수 있도록 재정의합니다.

// server/vite.ts (또는 __dirname을 사용하는 파일)
import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 이제 __dirname을 기존처럼 사용할 수 있습니다
export function serveStatic(app: Express) {
  const distPath = path.resolve(__dirname, "..", "public");
  // ...
}

 

4. parent snapshot does not exist

증상

ERROR: failed to prepare extraction snapshot "..." parent snapshot "..." does not exist: not found

Docker 빌드 중 캐시 관련 오류가 발생합니다.

원인

Docker의 빌드 캐시가 손상되어 이전에 캐시된 레이어를 찾을 수 없을 때 발생합니다.

해결책

--no-cache 플래그를 사용하여 캐시 없이 처음부터 다시 빌드합니다.

docker build --no-cache -t your-image-name .

추가 팁: 완전한 재배포 프로세스

문제 해결 후 변경사항을 적용하려면 다음 단계를 따라주세요:

# 1. 기존 컨테이너 중지 및 제거
docker stop your-container-name && docker rm your-container-name

# 2. 이미지 다시 빌드 (필요시 --no-cache 사용)
docker build -t your-image-name .

# 3. 새 컨테이너 실행
docker run -d --name your-container-name --env-file .env -p 3000:3000 your-image-name

# 4. 로그 확인
docker logs your-container-name

권장 Dockerfile 구조

위 문제들을 방지하기 위한 기본적인 Dockerfile 구조입니다:

FROM node:18-alpine

WORKDIR /app

# 의존성 설치
COPY package*.json ./
RUN npm ci --only=production

# 애플리케이션 코드 복사
COPY . .

# 빌드
RUN npm run build

# 환경 변수 설정
ENV NODE_ENV=production
ENV PORT=3000

# 포트 노출
EXPOSE 3000

# 애플리케이션 실행
CMD ["npm", "start"]