← 전체 프로젝트

PROJECT 08

AWS Deploy

풀스택 애플리케이션 배포 자동화 파이프라인

프로젝트 개요

AWS Deploy는 로컬에서만 동작하던 Todo 웹 애플리케이션을 AWS에 실제 서비스 형태로 배포한 1인 인프라 실습 프로젝트입니다. React 화면은 S3와 CloudFront로, Node.js/Express API는 Docker 이미지로 만들어 ALB 뒤 EC2에, 데이터는 RDS PostgreSQL에 두고, Route 53과 ACM으로 도메인과 HTTPS를 연결했습니다. 프론트엔드와 백엔드 모두 GitHub Actions로 빌드·배포를 자동화했습니다.

주요 구현

정적 화면과 API 배포 경로를 분리하고 GitHub Actions로 자동화했습니다.

진행 기간
2025.08 ~ 2025.09
팀 구성
1인 구축
담당 역할
인프라 설계 및 배포 자동화 구축

기술 스택

Application
Node.jsReactVite
Container / CI
DockerGitHub Actions
AWS
S3CloudFrontRoute 53ALBEC2RDSACM
배포 구조이미지를 누르면 원본을 볼 수 있습니다
AWS Route 53, CloudFront, S3, ALB, EC2, RDS와 GitHub Actions CI/CD 배포 구조를 보여주는 시스템 아키텍처
01 · 배포 구조정적 화면·API·데이터와 자동 배포 경로

01

서비스 소개

서비스 배경
로컬에서 동작하던 화면과 API를 클라우드에 올리려면 정적 리소스 배포, API 서버 운영, DB 연결, 도메인과 HTTPS, 반복 배포를 각각 구성해야 했습니다.
서비스 목표
정적 화면·API·데이터의 배포 경로를 나누고, 코드를 푸시하면 빌드와 배포가 자동으로 이어지게 합니다.
대상 사용자
실습 대상: React Todo 화면 · Express Todo API · PostgreSQL

주요 기능

  • 프론트엔드 배포

    Vite 빌드 결과를 S3에 올리고 CloudFront로 배포하며 캐시를 무효화합니다.

  • 백엔드 배포

    Docker 이미지를 빌드해 Docker Hub에 올리고 EC2 컨테이너를 교체합니다.

  • HTTPS API

    ALB와 ACM 인증서로 API를 HTTPS로 제공합니다.

  • 데이터베이스

    RDS PostgreSQL에 SSL로 연결하고, 연결 정보는 환경 변수로 주입합니다.

  • 도메인

    Route 53으로 화면과 API 도메인을 연결합니다.

  • 접근 제어

    Security Group으로 ALB → EC2, EC2 → RDS 경로만 허용합니다.

02

시스템 아키텍처

정적 리소스는 S3·CloudFront, 동적 API는 ALB·EC2, 데이터는 RDS로 경로를 분리했습니다. GitHub Actions 코드는 저장소에서 확인할 수 있고 AWS 리소스 연결은 콘솔 구성과 README 아키텍처로 관리했습니다.

구성 요소별 역할

  • Route 53

    www(프론트)와 api(백엔드) 레코드를 각각 CloudFront와 ALB로 라우팅

  • CloudFront + S3

    React 빌드 산출물을 S3 오리진에서 받아 CDN으로 배포, us-east-1 ACM 인증서 사용

  • ALB + ACM

    ap-northeast-2 인증서로 HTTPS(443)를 종료하고 EC2로 트래픽 전달

  • EC2 + Docker

    Node.js 서버를 컨테이너로 실행하고 GitHub Actions의 SSH 배포 대상으로 사용

  • RDS PostgreSQL

    Node.js 서버의 영속 데이터 저장소로 사용하고 환경 변수와 SSL 옵션으로 연결

  • GitHub Actions

    push를 트리거로 프론트는 S3에, 백엔드는 EC2에 배포하는 파이프라인 실행

03

구현 기능

전체 서비스 안에서 직접 구현하거나 공동으로 맡은 기능입니다.

  • 01

    Frontend 배포

    React Build 산출물을 S3 정적 호스팅에 올리고 CloudFront CDN으로 배포

  • 02

    Backend 배포

    GitHub Actions에서 Docker 이미지를 빌드해 EC2 컨테이너로 배포

  • 03

    Database 연동

    Node.js 서버가 환경 변수로 RDS PostgreSQL 연결 정보를 주입받고 SSL 옵션을 사용하도록 구성

  • 04

    HTTPS 구성

    HTTPS 프론트엔드에서 HTTP API가 차단되는 문제를 해결하기 위해 ALB와 ACM을 사용하는 HTTPS API 구조를 AWS 콘솔에서 구성

  • 05

    DNS 연결

    Route 53과 ACM을 이용한 도메인·인증서 연결을 구성하고 저장소 README에 전체 요청 경로를 문서화

기여 범위

별도 AWS 배포 실습입니다. self-hosted Runner·SSM 전환은 검토한 대안이며 현재 적용한 방식은 GitHub-hosted Runner의 SSH 배포입니다.

04

트러블슈팅

문제와 해결, 확인한 결과를 적고 실제 코드와 테스트를 근거로 붙였습니다.

문제 해결

Mixed Content — HTTPS 페이지의 HTTP API 차단

문제
HTTPS 페이지에서 HTTP API 요청이 브라우저에 차단되어 통신이 되지 않았습니다.
해결
ALB에 ACM 인증서를 연결해 API도 HTTPS로 제공하고, 프론트엔드 배포 시 HTTPS API 주소를 주입했습니다.
결과
브라우저의 Mixed Content 차단 없이 프론트엔드에서 API를 호출할 수 있게 했습니다.
판단 과정 단계별로 보기
  1. 프로토콜 불일치

    CloudFront는 HTTPS로 서빙되는데 EC2 API는 HTTP로 호출하고 있었습니다. Frontend와 Backend의 프로토콜이 어긋나 브라우저가 요청을 막았습니다.

  2. ALB + ACM 인증서 연결

    AWS 콘솔에서 ALB와 ACM 인증서를 연결해 Backend API Endpoint를 HTTPS로 구성하고, 프론트엔드는 배포 Secret의 API URL을 주입받도록 변경했습니다.

문제 해결

RDS 연결 오류 — 환경 변수와 SSL 확인

문제
배포 환경에서 PostgreSQL 연결 오류가 발생해 애플리케이션 설정과 AWS 네트워크 설정을 구분해 확인했습니다.
해결
컨테이너 로그를 기준으로 DB 환경 변수와 PostgreSQL SSL 옵션을 점검하고 연결 설정에 SSL 옵션을 추가했습니다.
결과
코드에 남는 연결 설정과 AWS 콘솔의 네트워크 설정을 구분해 점검할 수 있도록 정리했습니다.
판단 과정 단계별로 보기
  1. 연결 설정 범위 분리

    저장소에서 확인 가능한 원인은 런타임 환경 변수와 PostgreSQL SSL 옵션입니다. Security Group과 Secrets의 당시 값은 저장소에 남지 않아 코드만으로 장애 원인을 단정하지 않았습니다.

  2. 로그 기준 단계적 확인

    docker logs를 기준으로 DB 환경 변수와 SSL 연결 옵션을 확인하고 서버의 PostgreSQL Pool 설정에 SSL 옵션을 추가했습니다. AWS 콘솔 설정 변경은 별도 운영 작업으로 구분했습니다.

문제 해결

CI/CD SSH Timeout — 대안 검토

문제
GitHub Actions 배포 단계에서 EC2 SSH 연결 시간 초과가 발생했습니다.
해결
Runner의 접속 경로와 EC2 접근 정책을 점검했습니다. 고정된 접근 경로가 필요한 경우 self-hosted Runner 또는 SSM 전환을 검토했습니다.
결과
현재 배포는 GitHub-hosted Runner의 SSH 방식입니다. 당시 로그가 없어 Timeout 원인을 단정하지 않았습니다.
판단 과정 단계별로 보기
  1. Runner 네트워크 변동 가능성

    GitHub-hosted Runner는 고정 공인 IP를 보장하지 않으므로 특정 IP만 허용하는 EC2 접근 정책과 충돌할 수 있습니다. 당시 연결 로그가 저장소에는 남아 있지 않아 코드만으로 원인을 확정하지 않았습니다.

  2. 현재 방식과 대안

    현재 워크플로는 GitHub-hosted Runner에서 SSH로 배포합니다. 고정 접근이 필요한 경우 self-hosted Runner 또는 AWS SSM으로 전환하는 방안을 검토했습니다.

현재의 한계

GitHub Actions 워크플로와 애플리케이션 연결 코드는 저장소에서 검증할 수 있습니다. Route 53·ACM·ALB·Security Group의 실제 상태와 당시 장애 로그는 IaC로 관리되지 않아 AWS 콘솔 구성 경험으로 구분해 설명합니다.

05

기술 선택 이유

기술 이름보다 해결하려던 작업과 적용 이유를 적었습니다.

S3 · CloudFront

정적 화면 배포

정적 빌드 산출물을 API 서버와 분리해 CDN을 통해 제공합니다.

ALB · ACM · EC2

HTTPS API와 컨테이너 실행

HTTPS 화면의 HTTP API 요청이 차단되는 문제를 API 경로의 인증서와 프로토콜 구성으로 해결했습니다.

GitHub Actions · Docker

프론트·서버 배포 자동화

프론트는 S3, 서버는 컨테이너 이미지와 EC2로 나눠 각각의 배포 단계를 구성했습니다.

06

회고

배포 장애를 애플리케이션 코드와 인프라 설정으로 나눠 확인했습니다. 로그와 설정으로 확인한 사실과 당시 기록이 남지 않은 추정을 구분하는 것이 장애 설명의 기준이 됐습니다.