AIDCMap / Infrastructure guidedevtest.aidcmap.ai ↗
DEVELOPMENT ENVIRONMENT

개발환경, 한눈에.

프론트 배포부터 API 연결 확인까지.
새로운 AIDCMap을 위한 배포·운영 가이드입니다.

초기 검증 화면

Node.js 24 LTS · ECS Fargate
S3 · CloudFront · Private ALB · PostgreSQL

i
구성 상태를 확인하는 중입니다.

아래 기록은 배포 시점의 상태입니다. 실시간 연결은 ‘연결 검증’에서 확인하세요.

연결 검증 ↗
서비스 진입점도메인 하나프론트와 API가 같은 출처를 사용합니다
프론트엔드S3 + CloudFront현재 보고 있는 가이드도 S3에서 배포됩니다
백엔드Node.js on ECS상태 확인 필요 · /api/health
ARCHITECTURE

경로로 나누고, 하나로 연결합니다.

HTTPS
↗
devtest.aidcmap.ai브라우저 · HTTPS
↓
◇
CloudFront인증서 · 경로별 라우팅
단일 진입점
/*
▱
S3HTML · CSS · JavaScript

정적 파일은 OAC로만 읽습니다.
버킷 직접 공개는 차단합니다.

/api · /api/*
⇄
Private ALB → ECSNode.js · 8080 · Fargate

VPC 원본으로 비공개 ALB에 연결합니다.
API 캐시는 비활성화합니다.

↓PostgreSQL 17비공개 RDS · TLS · 5432
02 / DEPLOYMENT

배포 가이드

프론트는 파일로, 백엔드는 컨테이너 이미지로 배포합니다.

시작 전 · AWS CLI 로그인과 도구 준비 +

AWS CLI v2·Docker가 필요합니다. 백엔드 배포 도우미는 Python 3를 사용합니다. 아래 명령은 macOS/Linux 터미널 기준입니다.

SSO 설정에서 시작 URL은 https://gridwiz.awsapps.com/start/, SSO 리전은 ap-northeast-2, 계정은 242441135880, 권한 세트는 gw-aidcmap-operator를 선택하세요.

최초 한 번 프로필 설정 후 로그인
aws configure sso --profile aidcmap-dev
aws sso login --profile aidcmap-dev
export AWS_PROFILE=aidcmap-dev
export AWS_DEFAULT_REGION=ap-northeast-2
aws sts get-caller-identity

출력된 Account가 개발 계정과 일치하는지 확인하세요. 로그인 세션이 만료되면 aws sso login --profile aidcmap-dev를 다시 실행합니다.

1

정적 빌드 결과를 준비합니다.

프로젝트의 빌드 명령을 실행한 뒤 index.html이 들어 있는 폴더를 확인하세요. 아래는 npm·dist/ 기준 예시입니다. SSR 서버가 필요한 프론트는 S3 단독 배포 대상이 아닙니다.

터미널 · 프론트 프로젝트
npm ci
npm run build
# dist/ 대신 실제 빌드 결과 폴더를 사용하세요.
2

개발용 신규 S3에 업로드합니다.

승인된 AIDCMap 개발 계정·역할로 로그인한 후 실행하세요. 기존 gridwiz-aidcmap-dev 버킷과는 별개입니다. 삭제 옵션 없이 변경 파일만 업로드합니다.

AWS CLI · 개발 계정 로그인 후
aws sts get-caller-identity
aws s3 sync ./dist/ s3://gw-aidcmap-dev-web-242441135880/ \
  --cache-control "no-cache" --region ap-northeast-2
3

화면과 API를 함께 확인합니다.

현재 개발 배포는 캐시가 꺼져 있습니다. 새로고침 후 화면을 확인하고, 프론트의 API 기본 주소는 상대 경로 /api로 설정하세요. 실제 프론트를 업로드하면 초기 화면이 대체됩니다. 가이드는 /guide/index.html에서 계속 볼 수 있습니다.

연결 검사 실행하기 →
03 / CONNECTIONS

리소스 연결 가이드

어떤 자원이 어디에 연결되는지 확인하세요.

구성 기록
역할리소스연결 방식
진입점devtest.aidcmap.aiRoute 53 → CloudFrontHTTPS · devtest 전용 인증서
프론트gw-aidcmap-dev-web-242441135880S3 · 비공개 · 버전 관리CloudFront OAC로 읽기
API 라우팅gw-aidcmap-dev-api-albPrivate ALB · VPC 원본/api · /api/* → 대상 그룹 → 컨테이너 8080
이미지gw-aidcmap-dev-apiECR · 태그 덮어쓰기 금지작업 정의가 이미지 태그를 참조
실행 환경gw-aidcmap-dev-apiECS 클러스터 · Fargate · 0.25 vCPU / 0.5 GB실행 상태 확인 필요
데이터베이스gw-aidcmap-dev-postgresRDS PostgreSQL 17 · db.t4g.micro · gp3 20GB연결 상태 확인 필요
DB 인증정보gw-aidcmap-dev-db-apiSecrets Manager · 앱 전용 사용자ECS 시작 시 주입 · 관리자 인증정보와 분리
로그/ecs/gw-aidcmap-dev-apiCloudWatch Logs · 보관 14일Node.js 표준 출력·표준 오류
외부 통신gw-aidcmap-dev-nat전용 VPC · private subnet → NAT상태 확인 필요
01

API 경로는 유지됩니다.

/api/users 요청은 백엔드에도 동일한 경로로 전달됩니다. CloudFront가 /api를 제거하지 않습니다.

02

인증정보는 서버에서 관리합니다.

브라우저나 프론트 빌드에 AWS 키·DB 비밀번호·시크릿을 넣지 마세요. 필요한 값은 ECS 작업 역할과 Secrets Manager 등으로 연결합니다.

03

기존 환경은 유지합니다.

dev.aidcmap.ai의 배포 경로는 별도입니다. 신규 앱 검증이 끝난 후에 교체 절차를 진행합니다.

인프라 담당자 체크리스트 +
  • 최초 백엔드 배포 전 NAT와 ECR 이미지 준비 상태 확인
  • 컨테이너 포트·ALB 헬스체크·실제 Node.js 리스닝 포트 일치
  • Task Execution Role은 ECR 이미지·로그, Task Role은 실제 앱의 AWS 접근에 사용
  • 시크릿을 작업 정의에 연결할 때 Execution Role에 해당 시크릿만 읽기 허용
  • 앱의 외부 URL은 https://devtest.aidcmap.ai로 지정하고 프록시 신뢰 설정 검토
  • 프론트의 SPA 또는 정적 내보내기 방식에 맞춰 페이지 새로고침 경로 처리 확인
  • 서비스 이름과 Project=aidcmap, Environment=dev 태그 유지
04 / POSTGRESQL

Node.js와 PostgreSQL 연결

전용 DB 사용자와 TLS 연결을 사용합니다. 비밀번호는 프론트에 전달하지 않습니다.

PRIVATE · 5432
엔진PostgreSQL 17
개발용 최소 구성db.t4g.micro · 20GB
데이터 위치aidcmap / app
백업·보호7일 백업 · 삭제 보호
1

ECS에 연결 설정을 전달합니다.

아래 설정은 이미 검증용 서비스에 연결돼 있습니다. 새 앱 이미지에서도 동일한 환경변수 이름을 사용하면 연결 설정을 유지할 수 있습니다.

변수값 또는 참조관리 위치
DB_HOST전용 RDS의 내부 엔드포인트ECS 작업 정의 환경변수
DB_PORT5432ECS 작업 정의 환경변수
DB_NAMEaidcmapECS 작업 정의 환경변수
DB_USER앱 전용 사용자 · aidcmap_apiSecrets Manager의 username 필드
DB_PASSWORD앱 전용 비밀번호 · 화면에 표시하지 않음Secrets Manager의 password 필드

ECS는 시크릿을 작업 시작 시 읽습니다. 비밀번호 변경 시 DB 사용자·시크릿·ECS 재배포를 함께 맞춰야 합니다. API 실행 역할에는 앱 시크릿만 읽기 허용돼 있습니다.

2

공식 드라이버로 인증서를 검증합니다.

다운로드 예제에는 pg 드라이버, lockfile, AWS RDS CA 번들이 들어 있습니다. npm ci 후 실행하세요. 커넥션 풀은 기본 2개로 제한했습니다.

Node.js · 서버에서만 실행
import pg from 'pg';
import { readFileSync } from 'node:fs';

const pool = new pg.Pool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT || 5432),
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: 2,
  connectionTimeoutMillis: 5000,
  ssl: {
    ca: readFileSync(new URL('./rds-ca-bundle.pem', import.meta.url), 'utf8'),
    rejectUnauthorized: true,
    servername: process.env.DB_HOST,
  },
});

const result = await pool.query('SELECT 1 AS connected');
// 사용자 입력은 쿼리 문자열에 붙이지 말고 $1 등의 매개변수를 사용하세요.
3

실제 SQL 응답을 확인합니다.

/api/health/db는 PostgreSQL에서 실제 조회를 실행하고 현재 연결의 TLS 사용 여부를 확인합니다. 호스트·사용자·비밀번호·업무 데이터는 응답하지 않습니다.

HTTP 200 · DB 연결 정상 응답
{
  "status": "ok",
  "service": "aidcmap-api",
  "database": "connected",
  "tls": true
}

앱 사용자의 기본 스키마는 app입니다. 실제 테이블은 앱의 마이그레이션으로 이 스키마에 생성하세요. DB 서버 관리 권한은 앱에 부여하지 않았습니다.

DB 연결 검사 실행하기 →
개발자 PC에서 DB에 직접 접속되지는 않습니다.DB는 비공개 서브넷에 있고 ECS API 보안 그룹에서만 5432 접속을 허용합니다. GUI 도구가 필요하면 인프라 담당자와 SSM 터널 등 별도 접속 경로를 준비하세요.
05 / VERIFICATION

실제 요청으로 연결을 확인합니다.

구성 기록과 별개로, 현재 브라우저에서 직접 요청합니다.

01 / ENTRY검사 전

HTTPS 진입

현재 도메인과 HTTPS 접속을 확인합니다.

브라우저가 인증서를 검증한 접속인지 확인합니다.
02 / FRONTEND검사 전

S3 정적 파일

GET /guide/verification.txt

CloudFront를 거쳐 파일을 실제로 가져옵니다.
03 / BACKEND검사 전

Node.js API

GET /api/health

응답 상태와 JSON 서비스 식별자를 확인합니다.
04 / DATABASE검사 전

PostgreSQL

GET /api/health/db

실제 SQL 실행과 TLS 연결을 확인합니다.
API · DB 응답
연결 검사를 실행하면 실제 HTTP 상태와 응답이 여기에 표시됩니다.
백엔드 또는 DB 연결이 준비되지 않았다면 503 응답이 발생할 수 있습니다.
실패하면 어디를 확인하나요? +
  • S3 파일 403/404: 파일 업로드 여부·정확한 파일명·OAC 버킷 정책을 확인하세요.
  • API 503: ECS 서비스 실행 여부, 대상 그룹에 등록된 healthy 대상이 있는지 확인하세요.
  • API 502/504 또는 시간 초과: 컨테이너 포트·보안 그룹·앱 응답·VPC 원본 연결을 확인하세요.
  • HTTP 200이지만 JSON이 아님: API 요청이 정적 페이지로 라우팅되지 않았는지 확인하세요.
  • DB 검사 503: ECS의 DB 환경변수·시크릿 주입·DB 보안 그룹·인증서 번들·DB 사용자 권한을 확인하세요. TLS 검증은 끄지 마세요.
  • 이미지 가져오기 실패: ECR 태그·CPU 아키텍처·실행 역할·NAT 외부 연결을 확인하세요.