MIJI DApp Server Docs

Dev 배포 세팅 가이드 (GitHub Actions → ECR → CodeDeploy, Nginx 호스트 운영)

사전 준비 (AWS 리소스)

• 리전: ap-northeast-2
• ECR: asset-dev-server
• CodeDeploy: Application asset-dev-app, Deployment Group asset-dev-dg (대상: EC2 태그 CodeDeploy=asset-dev-app)
• S3(배포 번들): asset-dev-codedeploy-artifacts (경로 예: dev/deploy-<sha>.zip)
• Secrets Manager:
  • /dapp/dev/config (.env 전체)
  • /dapp/dev/corp/* (기업 지갑용)
• EC2(dev): t3.small (x86_64) + EIP, nginx 호스트 서비스, docker/compose, awscli, codedeploy-agent 설치
• 도메인/SSL: nginx(호스트)에서 인증서 관리, 80/443 오픈, 앱은 3000으로 리버스 프록시

리포지토리에 추가된 배포 자산

• appspec.yml
• scripts/before_install.sh, scripts/after_install.sh, scripts/start.sh, scripts/validate.sh
• docker-compose.deploy.yml (배포용: ECR 이미지 사용)
• .github/workflows/deploy-dev.yml (dev 브랜치용)
• IMAGE_TAG 파일은 Actions에서 생성되어 번들에 포함됨

GitHub Environments / Secrets (dev)

• Environment: dev (브랜치 보호: dev)
• Environments → Secrets에 아래를 등록
  • AWS_REGION=ap-northeast-2 (공통)
  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (ECR push + S3 + CodeDeploy 권한)
  • ECR_REGISTRY=<ACCOUNT_ID>.dkr.ecr.ap-northeast-2.amazonaws.com
  • ECR_REPO=asset-dev-server
  • CODEDEPLOY_APP=asset-dev-app
  • CODEDEPLOY_GROUP=asset-dev-dg
  • CODEDEPLOY_S3_BUCKET_DEV=asset-dev-codedeploy-artifacts

워크플로우 동작 (.github/workflows/deploy-dev.yml)

1) dev 브랜치 push → 트리거 2) AWS 자격 구성(access key) 3) Docker build & push → ECR (:sha, :latest) 4) IMAGE_TAG 파일 생성, appspec.yml/scripts/docker-compose*.yml와 함께 zip → S3 업로드 (dev/deploy-<sha>.zip) 5) CodeDeploy create-deployment 호출(S3 revision)

CodeDeploy 배포 동작

• 번들 수신 후 /home/ec2-user/app에 배치
• BeforeInstall: 기존 compose down, 폴더 초기화
• AfterInstall: 스크립트 실행권한 부여, AWS Secrets Manager /dapp/dev/config를 server/.env로 렌더링 (aws cli 필요, 경로는 AWS_ENV_SECRET_PATH로 override 가능)
• ApplicationStart: scripts/start.sh
  • IMAGE_TAG(파일/환경)와 IMAGE_REGISTRY로 이미지 결정 (기본 .../asset-dev-server:<tag>)
  • docker compose -f docker-compose.yml -f docker-compose.deploy.yml up -d
• ValidateService: /health 호출

Nginx 운영 (호스트)

• 컨테이너 분리, 호스트 nginx로 TLS 종료 및 3000 포워딩.
• 필요 시 scripts/reload_nginx.sh를 훅에 연결해 reload 가능(기본 미사용).

주의/보강 포인트

• dev 브랜치만 배포. main 배포는 별도 워크플로우 예정.
• .env 렌더링: AWS_ENV_SECRET_PATH(기본 /dapp/dev/config)로 경로 변경 가능.
• 헬스체크 URL 기본 /health, 필요 시 HEALTH_URL env로 override.

(참고) IAM 권한 요구사항

• 액세스 키로 사용할 IAM 사용자/역할에 아래 권한 필요
  • ECR: ecr:GetAuthorizationToken, 이미지 업로드 일체
  • S3: s3:PutObject, s3:PutObjectAcl (버킷 asset-dev-codedeploy-artifacts 하위)
  • CodeDeploy: codedeploy:CreateDeployment, codedeploy:Get*, codedeploy:List*

Nginx 호스트 준비(EC2 수동 작업)

• 패키지 설치: sudo amazon-linux-extras enable nginx1 (또는 sudo apt-get install nginx), sudo yum install -y nginx
• 서비스 활성화: sudo systemctl enable nginx && sudo systemctl start nginx
• 리버스 프록시 설정(예시: /etc/nginx/conf.d/app.conf)

  server {
    listen 80;
    server_name dev.asset.cccv.to;
    location / {
      proxy_pass http://127.0.0.1:3000;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
    }
  }
  

• 인증서/TLS(예: Let’s Encrypt with certbot) 1) 패키지 설치
  • Amazon Linux 2023: sudo dnf install -y certbot python3-certbot-nginx
  • Ubuntu: sudo apt-get install -y certbot python3-certbot-nginx 2) 방화벽/SG에서 80/443 허용 확인 3) Nginx 기본 서버블록(80)으로 도메인 라우팅 상태 확인 4) 인증서 발급 및 Nginx 자동 설정

       sudo certbot --nginx -d dev.asset.cccv.to --email admin@example.com --agree-tos --redirect
    

  • --redirect를 사용하면 80 → 443 리다이렉트 규칙 자동 적용
  • 여러 도메인/와일드카드가 필요하면 -d를 추가 나열 5) 자동 갱신 크론/타이머 확인
  • sudo systemctl status certbot.timer (systemd)
  • 수동 점검: sudo certbot renew --dry-run 6) 재배포 시 Nginx reload가 필요하면 CodeDeploy 훅에 scripts/reload_nginx.sh 연결
• 방화벽/보안그룹: 80/443 허용, SSH 22는 제한 CIDR.
• 배포 후 리로드 필요 시 CodeDeploy 훅에 scripts/reload_nginx.sh를 연결할 수 있음(기본 미사용).

Docker / Docker Compose 사전 설치 (Amazon Linux 2023 EC2, x86_64/amd64 기준)

• Docker (AL2023는 dnf 사용, amazon-linux-extras 없음)

  sudo dnf update -y
  sudo dnf install -y docker
  sudo systemctl enable docker
  sudo systemctl start docker
  sudo usermod -aG docker ec2-user
  

  *재로그인 후 docker ps로 권한 확인.

• Docker Compose v2 (바이너리 설치)

  sudo mkdir -p /usr/local/lib/docker/cli-plugins
  sudo curl -SL https://github.com/docker/compose/releases/download/v2.24.7/docker-compose-linux-x86_64 \
    -o /usr/local/lib/docker/cli-plugins/docker-compose
  sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
  docker compose version
  

  (ARM/Graviton일 경우 docker-compose-linux-aarch64 사용)

• awscli v2 (없다면)

  sudo dnf install -y awscli
  

  CodeDeploy 훅에서 설치하지 않고, 사전에 EC2에 준비해두는 것을 권장합니다. codedeploy-agent는 별도로 설치/활성화되어 있어야 합니다.

Redis 데이터 영속화 (dev)

• Terraform: EBS(gp3) 10GiB, /dev/sdf, delete_on_termination=false
• EC2 마운트 수동 예시:

  lsblk
  sudo file -s /dev/sdf
  sudo mkfs -t xfs /dev/sdf # 최초 1회만
  sudo mkdir -p /mnt/redis
  echo "/dev/sdf /mnt/redis xfs defaults,nofail 0 2" | sudo tee -a /etc/fstab
  sudo mount -a
  sudo chown ec2-user:ec2-user /mnt/redis
  

• docker-compose: Redis 서비스에 /mnt/redis:/data 바인드 마운트
• 주의: docker compose down -v 금지, EBS 교체 시 데이터 보존