MIJI DApp Server Docs

개발 환경 설정 가이드 V3 (DEV_README_V3.md)

DEV_README.md(v8)와 DEV_README_V2.md를 보완하는 추가 운영 지침입니다. CI/CD 자동화, 보안, 로컬 개발 시 유의사항을 보다 명확히 하기 위한 내용을 다룹니다.

1. CodeDeploy 리비전 전달 및 AppSpec 관리

• ECR 이미지 기반 배포를 사용할 때도 CodeDeploy는 appspec.yml과 배포 훅 스크립트가 담긴 리비전을 요구합니다.
• 권장 절차:
  1. .github/workflows/ 빌드 잡 종료 시, appspec.yml과 scripts/ 디렉터리를 포함한 아티팩트를 ZIP으로 묶어 S3에 업로드합니다. 예: deploy-bundle-${GITHUB_SHA}.zip.
  2. aws deploy create-deployment 호출 시 --revision 옵션으로 S3 버킷/키를 명시합니다.

     aws deploy create-deployment \
       --application-name Miji-NFT-Server-App \
       --deployment-group-name Miji-NFT-Server-Dev-Group \
       --deployment-config-name CodeDeployDefault.OneAtATime \
       --s3-location bucket=$,key=deploy-bundle-${GITHUB_SHA}.zip,bundleType=zip \
       --description "Deploy ${GITHUB_SHA}"
     

  3. appspec.yml 내부 files 섹션에서 docker-compose.yml 또는 필요한 설정 파일을 EC2 대상 경로에 복사하도록 지정합니다.
  4. scripts/pull_image.sh, scripts/start_server.sh에 실행 권한을 유지하고, 환경 변수(.env)는 SSM Parameter Store 또는 별도 스크립트로 배포 전 동기화합니다.
• CodeDeploy 애플리케이션/배포 그룹 이름, S3 버킷은 GitHub Actions의 변수(vars)로 관리해 하드코딩을 피합니다.

2. GitHub Actions 검증 단계 (Lint/Test)와 실패 기준

• build-and-push 잡에 품질 검증 단계를 추가합니다. ```yaml

  • name: Install dependencies run: pnpm install –frozen-lockfile

  • name: Run lint run: pnpm –filter server lint

  • name: Run unit tests run: pnpm –filter server test

  • name: Run e2e tests run: pnpm –filter server test:e2e ```

• 각 단계가 실패하면 잡이 즉시 중단돼야 하며, Docker 이미지 빌드/푸시는 수행되지 않습니다.
• 테스트가 장시간 소요된다면 timeout-minutes 값을 지정해 파이프라인이 무한 대기하지 않도록 합니다. 예: timeout-minutes: 15.
• pnpm --reporter junit 옵션을 활용하면 JUnit 리포트를 생성해 GitHub Actions에서 테스트 결과를 시각화할 수 있습니다.

3. GitHub Actions Secrets/Vars 정의 표

아래 표는 워크플로가 참조하는 값과 저장 위치를 정리한 것입니다.

| 키 | 유형 | 설명 | 저장 위치 | | — | — | — | — | | AWS_ACCESS_KEY_ID | Secret | Actions에서 AWS 인증용 Access Key | Repository Secrets | | AWS_SECRET_ACCESS_KEY | Secret | Actions에서 AWS 인증용 Secret Key | Repository Secrets | | AWS_REGION | Variable | 공통 AWS 리전 (예: ap-northeast-2) | Repository Variables | | ECR_REPOSITORY_NAME | Variable | Docker 이미지를 푸시할 ECR 리포지토리 이름 | Repository Variables | | CODEDEPLOY_APP_NAME | Variable | CodeDeploy 애플리케이션 이름 | Repository Variables | | CODEDEPLOY_DEPLOYMENT_GROUP | Variable | CodeDeploy 배포 그룹 이름 | Repository Variables | | CODEDEPLOY_S3_BUCKET | Variable | CodeDeploy 번들을 업로드할 S3 버킷 | Repository Variables | | CODEDEPLOY_SERVICE_ROLE | Variable (선택) | CodeDeploy에서 사용할 IAM Role ARN (필요 시) | Repository Variables | | DOCKER_IMAGE_TAG | Variable (선택) | 태그 전략(예: $) 정의 시 사용 | Repository Variables |

• 팀 내 공유가 필요한 추가 secrets/vars가 생기면 표에 행을 추가해 추후 유지보수를 돕습니다.

4. LOCAL_DEV_PK 사용 시 보안 주의사항

• LOCAL_DEV_PK는 로컬 개발 및 테스트 전용으로만 사용합니다.
  • NODE_ENV=production 또는 staging일 때는 해당 값을 무시하고 반드시 AWS Secrets Manager에서 PK를 조회하도록 방어 로직을 구현합니다.
  • 로컬 .env 파일이나 예제에 저장하는 키는 절대 실제 자금을 보유한 지갑을 사용하지 않습니다.
• Git 저장소에는 기본값을 비워 둔 .env.example만 커밋하고, 실제 PK 값이 담긴 .env는 ignore 처리합니다.
• 로컬 개발자가 테스트를 마친 뒤에는 .env 파일을 삭제하거나 키를 회전해, 오프라인에 남지 않도록 권장합니다.
• CI 환경(예: GitHub Actions)에서 통합 테스트를 수행할 때는 LOCAL_DEV_PK 대신 Secrets Manager Mock이나 임시 시크릿을 사용하도록 별도 설정을 두어 실수로 프로덕션 키를 사용하지 않게 합니다.

5. Redis 영속화 및 복구 절차

• docker-compose.yml의 Redis 서비스는 redis-data 볼륨을 /data에 마운트하고 --appendonly yes --appendfsync everysec 옵션을 사용합니다. 로컬/운영 모두 동일하게 구성하면 컨테이너 재시작 시 큐·nonce 데이터가 유지됩니다.
• 프로덕션 Redis(Elasticache 등)를 사용하더라도 AOF + 주기적 RDB 스냅샷을 권장합니다. AOF만 사용할 경우 appendfsync everysec 이상을 적용해 장애 시 최대 1초 데이터 손실로 제한합니다.
• Redis를 초기화하거나 장애 복구를 수행한 직후에는 아래 순서를 따르면 됩니다.
  1. API 서버를 재기동하면 JanitorService가 부트스트랩 단계에서 MongoDB의 status: DEPLOYING 컨트랙트와 PENDING/PROCESSING 민팅 주문을 Bull 큐에 다시 등록합니다.
  2. Nonce는 CLI 스크립트(pnpm --filter server redis:sync-nonce <chainId> <address>)로 RPC의 getTransactionCount(..., 'pending') 값을 Redis에 다시 기록합니다. 배포 지갑/Relayer 주소 목록을 운영 문서에 명시하세요.
  3. Bull 큐를 수동 재시작해야 하는 특수 상황에서는 MongoDB의 DeployedContract/MintingOrder 문서를 기준으로 재등록하면 됩니다. JanitorService Cron(@Every5/10분)도 주기적으로 동일 작업을 수행하지만, 이제 txHash가 이미 기록된 주문은 재삽입하지 않습니다.
• 현재 Redis가 비영속 모드로 실행되는 환경이 있다면 반드시 운영 노트에 기록하고, 스냅샷/AOF 요구사항 및 재기동 시 수행할 절차(위 순서)를 문서화하여 배포 담당자가 참고할 수 있게 합니다.

6. 메타데이터 Base URI 설정

• .env에 METADATA_BASE_URI를 정의하면(예: https://api.miji.dev/metadata) 컨트랙트 배포 시 별도 값이 없을 때 기본 Base URI로 사용합니다.
• POST /contracts/deploy 요청에서 metadataBaseUri 필드를 지정하면 해당 값이 우선 적용됩니다.
• 배포 직후 Processor가 아래와 같이 컨트랙트에 URI를 세팅합니다.
  • ERC-721: <base>/<contractAddress>/
  • ERC-1155: <base>/<contractAddress>/{id} (OpenSea 규격 {id} 플레이스홀더)
• 따라서 API 서버의 GET /metadata/:contractAddress/:tokenId가 자동으로 tokenURI와 연결되어, 별도의 수동 세팅 없이 메타데이터가 노출됩니다.

---

상기 내용은 기존 문서의 흐름을 유지하면서 세부 운영 사항을 명문화하기 위한 것이며, 변경 사항 반영 후 DEV_README.md와 DEV_README_V2.md의 해당 챕터에 링크를 추가하면 참고성이 높아집니다.