전체 흐름 #
- 개발에 필요한 환경 구성
- 소스 코드 취득 및 의존 패키지 설치
- 개발 서버에서 동작 확인
- 프로덕션 빌드 생성
- Nginx 설정을 구성하여 빌드된 파일 배포
- HTTPS 적용(필요 시)
- 재시작 시 자동 시작(필요 시)
아래 절차서에서는 구체적인 작업 예시를 제시합니다.
STEP1. 개발 환경 준비 #
STEP1.1 Node.js와 npm 설치 #
Ubuntu의 경우, 다음 명령어로 Node.js와 npm을 설치합니다.
sudo apt update
sudo apt install -y nodejs npm
설치 후 버전을 확인합니다.
node -v
npm -v
STEP1.2 서버 준비 #
- Ubuntu 등의 Linux 서버를 준비하고, SSH로 로그인할 수 있는 상태로 설정합니다.
- (프로덕션 운영을 전제로 하므로) root 또는 sudo 권한이 있는 사용자를 준비하세요.
STEP2. 소스 코드 취득 #
STEP2.1 소스 코드 다운로드/클론 #
- GitHub 등에 있는 경우
git clone https://...로 취득 - Zip 파일인 경우 업로드 후 압축 해제
- 이하에서는
/home/project에 배치했다고 가정합니다.
STEP2.2 의존 패키지 설치 #
소스 코드가 있는 디렉터리로 이동하여, npm install로 필요한 라이브러리를 설치합니다.
cd /home/project
npm install
성공하면 node_modules 디렉터리가 생성됩니다.
STEP3. 개발 서버에서 동작 확인 #
개발 시에는 npm run dev를 사용하여 로컬에서 간이 서버를 실행합니다. 다음은 한 예시입니다.
npm run dev
실행하면 터미널에 Local: http://localhost:5173와 같은 로그가 표시됩니다.
브라우저에서 해당 URL에 접속하면 앱이 동작하는 것을 확인할 수 있습니다.
- 원격 서버에서 테스트하려면
vite.config.ts의server.host를0.0.0.0으로 설정하여 외부에서 접근 가능하도록 하세요.
STEP4. 프로덕션 빌드 생성 #
개발이 안정화되면, 프로덕션용 빌드를 생성합니다. 이는 앱을 최적화하고, dist 디렉터리에
최종적인 정적 파일(HTML/JS/CSS)을 생성하는 과정입니다.
cd /home/project
npm run build
- 성공하면, 프로젝트 루트에
dist폴더가 생성됩니다. - 내부에는
index.html과assets폴더 등이 포함됩니다.
STEP5. Nginx로 빌드된 파일 배포 #
Vite의 프리뷰 서버가 아닌, Nginx 등의 웹 서버에서 정적 파일을 배포하는 것이 일반적입니다.
STEP5.1 Nginx 설치 #
Ubuntu에서 Nginx를 설치합니다.
sudo apt update
sudo apt install -y nginx
설치 후, 브라우저에서 http://<서버 IP 주소>/에 접속하면
“Welcome to nginx!”라는 페이지가 표시됩니다.
STEP5.2 프로덕션 파일 배치 #
- 배포 폴더 생성 (예:
/var/www/myapp)sudo mkdir -p /var/www/myapp - 빌드된 파일(
dist내용) 복사sudo cp -r /home/project/dist/* /var/www/myapp/ - 배치 후, 내용 확인
ls -l /var/www/myapp # index.html과 assets 폴더가 있으면 OK
STEP5.3 Nginx 설정 파일 생성 #
Nginx는 설정 파일 server { ... } 블록을
sites-available/ → sites-enabled/에서 관리하는 것이 표준입니다.
- 새 설정 파일 생성
sudo nano /etc/nginx/sites-available/myapp.conf - 아래 내용 작성 (SPA를 고려한 설정 예시)
server { listen 80; server_name _; # IP 접근만 사용할 경우. 도메인이 있다면 server_name example.com; root /var/www/myapp; # dist 파일 배치 경로 index index.html; # SPA 대응 설정: 라우터 경로가 /xxx인 경우에도 index.html로 폴백 location / { try_files $uri $uri/ /index.html; } }server_name은 프로덕션 도메인을 사용한다면 예:server_name example.com;root /var/www/myapp;는 빌드된 파일을 배치한 디렉터리 지정try_files $uri $uri/ /index.html;은 React Router 등을 사용하여, URL 직접 입력 시에도index.html로 폴백하기 위한 설정
- 설정 파일 활성화 및 기본 설정 비활성화
# 심볼릭 링크로 myapp.conf를 sites-enabled에 배치 sudo ln -s /etc/nginx/sites-available/myapp.conf /etc/nginx/sites-enabled/ # 기본 사이트가 있는 경우 비활성화 sudo rm /etc/nginx/sites-enabled/default - nginx 설정 파일의 문법 체크 & 리로드
sudo nginx -t sudo systemctl reload nginx - 브라우저에서
http://<서버의 IP>/에 접속- 이전의 “Welcome to nginx!”가 아닌 빌드한 앱이 표시되면 OK입니다.
STEP6. HTTPS (SSL) 도입(필요에 따라) #
운영 환경에서는 https:// 에 대응하는 것이 일반적입니다.
무료 Let’s Encrypt (Certbot)를 사용하는 예시:
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
대화식으로 진행하면 자동으로 nginx가 SSL 설정을 조합하여 HTTPS로 접속할 수 있게 됩니다.
(DNS가 yourdomain.com을 이 서버로 향하도록 설정되어 있어야 합니다)
STEP7. 재시작 시 자동 시작 #
STEP7.1 정적 파일만 있는 경우 #
Vite로 빌드한 정적 파일을 nginx가 배포하는 경우,
nginx가 자동 시작되어 있으면 특별한 문제가 없습니다. 아래 활성화가 완료되었는지 확인합니다.
sudo systemctl enable nginx
이렇게 하면 서버 재시작 시에도 자동으로 nginx가 시작됩니다.
STEP7.2 Node.js + Express / API서버가 있는 경우 #
만약 백엔드로 Node.js가 필요하고 같은 서버에서 실행하는 경우, PM2 또는 systemd로 Node.js 프로세스를 상주화하는 것이 일반적입니다.
# PM2 설치
sudo npm install -g pm2
# 앱(Express 등)을 시작
pm2 start "npm run start" --name my-backend
# 자동 시작 활성화
pm2 startup systemd
pm2 save
nginx는 /api/로의 요청만 Node.js로 proxy_pass 하고,
프론트엔드는 정적 파일로 배포하는 구성이 됩니다.
STEP8. 트러블슈팅 #
- “Welcome to nginx!” 그대로인 경우
- 기본 설정을 비활성화하지 않음
server_name이 일치하지 않음
- 404 오류가 발생하는 경우
root설정 경로가 잘못됨- SPA에서
try_files를 설정하지 않음
- 브라우저에서 접속할 수 없는 경우
- 포트 80/443을 개방하지 않음(클라우드의 보안 그룹 또는 UFW)
- 서버 IP나 도메인 이름이 올바르게 할당되지 않음
STEP9. 정리 #
- 개발:
npm run dev로 동작 확인 - 빌드:
npm run build→dist폴더 생성 - nginx로 배포:
dist의 내용물을/var/www/myapp에 배치 →myapp.conf를 설정 →nginx -t→systemctl reload nginx - HTTPS 대응:
certbot --nginx -d yourdomain.com등으로 인증서 취득 - 자동 시작: 정적 파일만이면 nginx, 자체 API도 필요하면 PM2 또는 systemd로 Node.js를 상주 관리
