MIJI DApp Server Docs

초기 세팅 가이드 (Corporate Edition)

이 문서는 새 환경에 서버를 올리기 전에 반드시 준비해야 하는 항목을 정리합니다.
모든 단계는 x-api-key + X-CORPORATE-ID 기반 인증을 전제로 합니다.

1. MongoDB 초기화 및 필수 데이터 입력

  1. DB 초기화
    • 기존 테스트 데이터(deployedContracts, mintingOrders, transferOrders, metadata, corporateAccounts)를 모두 드롭합니다.
    • 로컬 개발이면 docker compose down -v 후 up --build로 볼륨을 리셋해도 됩니다.

  2. corporateAccounts 컬렉션 생성
    아래 필드는 최소로 필요합니다.

    {
  "corporateId": "corp-demo-001",          // X-CORPORATE-ID 헤더 값
  "corporateName": "Demo Corp",
 "secretManagerKeyId": "arn:aws:secretsmanager:ap-northeast-2:123456789012:secret:/dapp/dev/corp/corp-demo-001/wallet",
  "walletAddress": "0x....",
  "walletLinkType": "DEDICATED",
  "metadata": { "contact": "ops@example.com" },
  "status": "ACTIVE"
}

    주의: corporateId는 UUID 등 예측 불가한 값으로 설정하고 Unique Index를 걸어둡니다.

    • 반복 입력이 번거롭다면, mongosh 기반 자동화 스크립트를 사용할 수 있습니다. 
       chmod +x scripts/upsert_corporate_account.sh
    ./scripts/upsert_corporate_account.sh \
    -u "mongodb+srv://admin:HzOckYOllX89dZof@dappmongodb.pug4qy8.mongodb.net/dapp_dev" \
 -c 98297d12311a9e1442088fe7b18fe \
    -n corp-dev-001 \
    -w 0x80CD25A5c39b2DBEdFf23A4AF5C6e5DA332c2113 \
 -s arn:aws:secretsmanager:ap-northeast-2:371711804553:secret:/dapp/dev/corp/corp-dev-001/wallet \
    -d dapp_dev \
      • -M metadata.json 옵션으로 메타데이터 JSON을 같이 넣을 수 있습니다.
      • 스크립트는 corporateId 기준으로 upsert를 수행합니다.
  3. 기본 Forwarder 레코드(선택)
    • 이미 배포된 MinimalForwarder가 있다면 deployedContracts에 ercStandard: 'Forwarder', corporateId를 포함하여 저장합니다.
    • 없으면 POST /contracts/forwarder로 새로 배포 (헤더에 해당 기업의 x-api-key, X-CORPORATE-ID 필요).

2. AWS Secrets Manager 준비

  1. 기업별 Private Key 저장
    • 각 기업의 지갑 Private Key를 Secrets Manager에 등록합니다.
    • 이름/ARN은 corporateAccounts.secretManagerKeyId에 저장한 값과 1:1 매칭되어야 합니다.
    • 권장 네이밍: secret:/dapp/{env}/corp/{corporateId}/wallet (예: /dapp/dev/corp/corp-dev-001/wallet, /dapp/prod/corp/corp-prod-001/wallet)
    • aws CLI가 설정돼 있다면 아래 스크립트로 손쉽게 생성/업데이트 할 수 있습니다. 
      chmod +x scripts/create_corporate_secret.sh
 ./scripts/create_corporate_secret.sh \
  -i /dapp/dev/corp/corp-dev-001/wallet \    # 신규 생성 시 "이름" 사용 (ARN 불가)
  -K "0x533efa3d38ce7759fcfacf2872b252a2d36f3c96bb45c6c80813f35980f4875e" \
  -p sinbumu -f
    • 신규 생성 시 ARN 사용 금지: create-secret는 ARN을 받지 않으므로 반드시 이름(/dapp/dev/corp/corp-dev-001/wallet)을 사용합니다. 이후 업데이트 시에는 이름 또는 ARN 모두 사용 가능.
    • 이미 존재하는 Secret을 덮어쓸 때는 -f 옵션을 추가합니다.
    • 파일 대신 바로 개인키 문자열을 전달하려면 -K 0x... 형태로 사용할 수 있습니다.
    • 파일을 사용하려면 예시처럼 입력합니다: 
      ./scripts/create_corporate_secret.sh \
  -i corp-demo-001 \
  -k ./keys/corp-demo-001.pk \
  -p miji-dev -f
  2. IAM 권한
    • 프로덕션: API 서버가 돌게 될 EC2/Pod에 GetSecretValue 권한만 있는 IAM Role을 부여합니다.
    • Resource를 프리픽스 제한으로 묶습니다:
      • arn:aws:secretsmanager:ap-northeast-2:371711804553:secret:/dapp/dev/corp/* (dev 예시)
      • arn:aws:secretsmanager:ap-northeast-2:371711804553:secret:/dapp/prod/corp/* (prod 예시)
    • 필요 시 태그 조건(aws:ResourceTag/env=dev|prod)을 추가해 교차 접근을 방지합니다.
    • 개발/QA: .env에 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY를 넣되, 테스트 Secret만 접근 가능한 최소 권한 키를 사용합니다.
  3. 로컬 개발용 키 (옵션)
    • .env에 blockchain.localDevPrivateKey를 넣으면 X-CORPORATE-ID 없이 테스트할 때 fallback 키로 사용됩니다.
    • 단, MVP 모드에서는 모든 보호 API에 X-CORPORATE-ID를 보내야 하므로, 실제 호출 시에는 corporate 계정을 생성하는 것이 권장됩니다.

3. 환경 변수 점검

필수 .env 항목:

키 설명
GLOBAL_SECRET_KEY x-api-key 목록 (쉼표 구분)
NODE_ENV development / production
CHAIN_RPC_URLS 체인별 RPC (예: { "43113": "https://..." })
deployment.allowedChainIds 허용 체인 목록
BLOCKCHAIN_PK_SECRET_ARN (Fallback) 시스템용 기본 Secret ARN (기업 ID 미지정 시 사용)
forwarder.address Fallback Forwarder 주소 (DB/요청에 없을 때)
COINGECKO_*, REDIS_*, DB_URI 기존과 동일

4. 서버 기동 전 체크리스트

  1. pnpm install → pnpm --filter contracts build → pnpm --filter server build
  2. pnpm --filter server lint && pnpm --filter server test
  3. docker compose up --build (또는 ECS/쿠버네티스 배포)
  4. 서버 기동 후 헬스체크:
    • GET /health (Public)
    • GET /status (헤더 필요)
    • POST /contracts/read로 isTrustedForwarder 테스트 (x-api-key + X-CORPORATE-ID)

5. 운영 중 유의 사항

이 문서는 MVP 운영의 필수 baseline입니다. 추가 요구사항이 생기면 이 문서를 업데이트하세요.