React 프로젝트 Ubuntu 서버 배포 완벽 가이드

Linkmoa 프로젝트를 통해 배운 실전 배포 경험을 바탕으로 작성한 완벽한 배포 가이드입니다.

🎯 배포 목표 및 환경 설정

프로젝트 환경

• 프론트엔드: React + Vite + TypeScript
• 서버: Ubuntu 24.04.2 LTS
• 웹서버: nginx
• 배포 방식: 정적 파일 배포 (SCP 사용)
• 도메인: https://linkrew.com
• API 서버: https://api.linkrew.com

---

📋 1단계: 사전 준비 및 점검

1-1. 로컬 환경 점검

# 프로젝트 디렉토리로 이동
cd Documents/portfolio/Linkmoa-frotnend

# Git 상태 확인
git status
git branch

# 의존성 설치 확인
npm install

1-2. 환경변수 설정 확인

# 환경변수 파일들 확인
ls -la .env*

# 각 환경별 설정 확인
cat .env.production
# 내용 예시:
# VITE_API_BASE_URL=https://api.linkrew.com
# VITE_API_URL=https://api.linkrew.com
# VITE_GA_MEASUREMENT_ID=G-03JHMHP2XX

⚠️ 주의사항: .env.local 파일에서 중복 설정이나 오타가 없는지 반드시 확인!

1-3. SSH 접속 설정 확인

# SSH 설정 확인
cat ~/.ssh/config

# 예시 설정:
# Host linkmoa-web-dev-ubuntu
#     HostName 192.168.0.79
#     Port 22
#     User ubuntu
#     IdentityFile ~/.ssh/linkmoa-web-dev-ubuntu.pem
#     ProxyJump linkmoa-proxy-jump

# 접속 테스트
ssh linkmoa-web-dev-ubuntu
exit

---

🔧 2단계: 서버 환경 확인

2-1. nginx 설정 확인

# 서버 접속
ssh linkmoa-web-dev-ubuntu

# nginx 설정 확인
sudo cat /etc/nginx/sites-available/default | grep -E "root|server_name"

# 예상 결과:
# root /home/ubuntu/linkrew;
# server_name _;

# nginx 상태 확인
sudo systemctl status nginx

2-2. 배포 경로 확인

# 현재 배포 경로 확인
ls -la /home/ubuntu/linkrew/

# 기존 파일 백업 (선택사항)
sudo cp -r /home/ubuntu/linkrew /home/ubuntu/linkrew.backup.$(date +%Y%m%d_%H%M%S)

---

🚀 3단계: 프로젝트 빌드

3-1. 프로덕션 빌드 실행

# 로컬에서 실행
npm run build

# 빌드 성공 시 예상 출력:
# ✓ 363 modules transformed.
# dist/index.html                    0.53 kB
# dist/assets/index-[hash].css       41.23 kB
# dist/assets/index-[hash].js        969.69 kB
# ✓ built in 1.79s

3-2. 빌드 결과 확인

# dist 폴더 내용 확인
ls -la dist/

# 예상 구조:
# drwxr-xr-x  assets/
# -rw-r--r--  index.html
# -rw-r--r--  LinkLogo.svg

💡 팁: 빌드 시 chunk size 경고가 나와도 배포에는 문제없습니다. 성능 최적화는 별도로 진행하세요.

---

📤 4단계: 파일 전송

4-1. 서버 임시 디렉토리 준비

# 기존 임시 디렉토리 삭제 후 새로 생성
ssh linkmoa-web-dev-ubuntu "rm -rf ~/temp-dist && mkdir -p ~/temp-dist"

4-2. 빌드 파일 업로드

# SCP를 사용한 파일 전송
scp -r dist/* linkmoa-web-dev-ubuntu:~/temp-dist/

# 업로드 진행 상황 확인
# 파일명들과 전송 속도가 표시됨:
# index.html                    100%  528    65.7KB/s   00:00
# LinkLogo.svg                  100% 1972   246.4KB/s   00:00
# assets/index-[hash].js        100%  960KB  17.8MB/s   00:00

🔥 트러블슈팅: zsh: no matches found: dist/* 에러 발생 시 현재 디렉토리가 프로젝트 루트인지 확인하세요.

---

🔄 5단계: 서버 배포

5-1. 서버 접속 및 파일 확인

# 서버 접속
ssh linkmoa-web-dev-ubuntu

# 업로드된 파일 확인
ls -la ~/temp-dist/

# 다음 파일들이 있어야 함:
# - index.html
# - LinkLogo.svg
# - assets/ (디렉토리)

5-2. 운영 환경으로 파일 배포

# 기존 파일 삭제
sudo rm -rf /home/ubuntu/linkrew/*

# 새 파일 복사
sudo cp -r ~/temp-dist/* /home/ubuntu/linkrew/

# 권한 설정
sudo chown -R ubuntu:ubuntu /home/ubuntu/linkrew/
sudo chmod -R 755 /home/ubuntu/linkrew/

# 복사 결과 확인
ls -la /home/ubuntu/linkrew/

5-3. nginx 재시작

# nginx 설정 테스트
sudo nginx -t

# nginx 재시작
sudo systemctl restart nginx

# nginx 상태 확인
sudo systemctl status nginx
# Active: active (running) 상태 확인

# 서버에서 로그아웃
exit

---

✅ 6단계: 배포 확인 및 테스트

6-1. 브라우저 접속 테스트

# 브라우저에서 다음 URL들로 접속:
# - http://192.168.0.79 (서버 IP 직접 접속)
# - https://linkrew.com (도메인 접속)

6-2. API 연결 확인

# 브라우저 개발자 도구 (F12) → Network 탭에서 확인:
# 1. API 요청 URL이 올바른지 (https://api.linkrew.com)
# 2. 응답 상태 코드가 정상인지
# 3. CORS 에러가 없는지

6-3. 기능별 테스트

• 로그인/로그아웃: 인증 토큰 정상 처리
• 폴더 관리: 생성, 수정, 삭제, 전송
• 알림 시스템: 실시간 알림 수신
• 파일 업로드: 이미지 및 링크 처리

---

🚨 트러블슈팅 가이드

문제 1: API 요청이 실패하는 경우

# 환경변수 확인
cat .env.production
# VITE_API_URL이 올바른 프로덕션 서버를 가리키는지 확인

# .env.local 파일 중복 설정 제거
nano .env.local
# 중복된 VITE_API_URL 설정 제거

문제 2: 빈 페이지가 표시되는 경우

# 서버에서 파일 확인
ssh linkmoa-web-dev-ubuntu
ls -la /home/ubuntu/linkrew/
cat /home/ubuntu/linkrew/index.html

# nginx 에러 로그 확인
sudo tail -n 20 /var/log/nginx/error.log

문제 3: 권한 에러 발생 시

# 권한 재설정
sudo chown -R ubuntu:ubuntu /home/ubuntu/linkrew/
sudo chmod -R 755 /home/ubuntu/linkrew/

# nginx 유저 확인
ps aux | grep nginx

문제 4: nginx 설정 문제

# nginx 설정 확인
sudo cat /etc/nginx/sites-available/default

# 설정 테스트
sudo nginx -t

# 포트 확인
sudo ss -tlnp | grep nginx

---

🎯 배포 자동화 스크립트

전체 배포 과정을 자동화하는 스크립트

#!/bin/bash
# deploy.sh

echo "🚀 배포 시작..."

# 1. 빌드
echo "📦 프로젝트 빌드 중..."
npm run build

# 2. 파일 전송
echo "📤 파일 업로드 중..."
ssh linkmoa-web-dev-ubuntu "rm -rf ~/temp-dist && mkdir -p ~/temp-dist"
scp -r dist/* linkmoa-web-dev-ubuntu:~/temp-dist/

# 3. 서버 배포
echo "🔄 서버 배포 중..."
ssh linkmoa-web-dev-ubuntu << 'EOF'
sudo rm -rf /home/ubuntu/linkrew/*
sudo cp -r ~/temp-dist/* /home/ubuntu/linkrew/
sudo chown -R ubuntu:ubuntu /home/ubuntu/linkrew/
sudo chmod -R 755 /home/ubuntu/linkrew/
sudo systemctl restart nginx
EOF

echo "✅ 배포 완료!"
echo "🌐 https://linkrew.com 에서 확인하세요."

스크립트 사용법

# 실행 권한 부여
chmod +x deploy.sh

# 배포 실행
./deploy.sh

---

📝 배포 체크리스트

배포 전 확인사항

• Git 브랜치가 main/master인지 확인
• .env.production 파일 설정 확인
• .env.local 파일에 중복 설정 없는지 확인
• npm run build 성공 확인
• SSH 접속 가능 확인

배포 후 확인사항

• 브라우저에서 사이트 정상 접속
• API 요청이 올바른 서버로 전송
• 모든 기능 정상 작동
• 브라우저 콘솔에 에러 없음
• 모바일 반응형 정상 작동

---

💡 배포 최적화 팁

1. 성능 최적화

# 이미지 최적화
# - WebP 포맷 사용
# - 이미지 크기 최적화

# 번들 사이즈 최적화
# - dynamic import() 사용
# - 불필요한 라이브러리 제거

2. 보안 강화

# HTTPS 강제 설정
# SSL 인증서 설정
# 보안 헤더 추가

3. 모니터링 설정

# nginx 로그 모니터링
sudo tail -f /var/log/nginx/access.log

# 시스템 리소스 모니터링
htop
df -h

---

🎉 마무리

이 가이드를 통해 React 프로젝트를 Ubuntu 서버에 성공적으로 배포할 수 있습니다. 핵심은 환경변수 설정과 파일 권한 관리입니다.

기억할 점:

• 로컬과 프로덕션 환경의 API URL 분리
• 빌드 → 전송 → 배포 → 확인의 체계적인 순서
• 문제 발생 시 로그 확인의 중요성

Happy Deploying! 🚀