메두사(Medusa) 스탠드얼론 설치 가이드 (Ubuntu 22.04, Docker 미사용)

소개 (Medusa란?)

Medusa는 Node.js 기반의 오픈 소스 헤드리스 커머스 플랫폼으로, 유연한 모듈식 아키텍처를 통해 전자상거래 백엔드 기능을 제공합니다. Medusa 서버(백엔드)는 PostgreSQL 데이터베이스를 기본 저장소로 사용하고, Redis를 세션/캐시 및 이벤트 처리 등에 활용합니다. Medusa의 관리자 대시보드(Admin)와 스토어프론트(Storefront)는 모두 이 백엔드의 REST API를 통해 동작하는 클라이언트 응용 프로그램입니다. 본 가이드에서는 Ubuntu 22.04 환경에 Docker를 사용하지 않고 Medusa 백엔드와 필요한 서비스들(PostgreSQL, Redis, MinIO 등)을 개별 설치하여, 추가 개발 및 운영이 가능한 스탠드얼론 환경을 구축하는 방법을 자세히 설명합니다. 또한 서비스 간 연동 구조, 설치 순서, Git 저장소 구성 전략(모노레포 vs 서브모듈)과 더불어, Medusa를 활용한 아마존 마켓플레이스 연동 모듈 개발 방안(주문 동기화, 재고 관리, 상품 등록)을 함께 다룹니다.

Medusa 아키텍처 개요 및 구성 요소

Medusa 애플리케이션은 Node.js 서버(Medusa Core)와 관리자 대시보드(Admin)로 구성되며, 선택적으로 Next.js 기반 스토어프론트(Storefront)를 추가할 수 있습니다. Medusa 백엔드 서버는 Express.js 기반으로 요청을 처리하며, 내부적으로 PostgreSQL 데이터베이스와 연결되어 영구 데이터를 관리합니다. 또한 세션 및 이벤트/잡 처리를 위해 Redis를 통합하여 사용하며, 상품 이미지 등의 파일 업로드를 위해 파일 스토리지 모듈이 필요한데, 여기서는 S3 호환 스토리지인 MinIO를 사용합니다. 이러한 백엔드 서비스들을 기반으로, Admin 대시보드(관리자용 웹 UI)와 스토어프론트(고객용 웹 스토어)가 Medusa의 REST API에 접근하여 상점 기능을 구현합니다.

Medusa 백엔드와 연결 서비스들 아키텍처: Medusa Node.js 서버(백엔드)는 PostgreSQL 데이터베이스와 Redis 캐시/이벤트 서버에 연결되며, Admin 대시보드와 Storefront는 백엔드의 API를 통해 기능을 소비합니다. (MinIO와 같은 파일 스토리지는 파일 업로드를 처리하는 Infrastructure Module로 통합됩니다.)

설치 전제조건 및 환경 준비

스탠드얼론 Medusa 설치를 위해 우선 다음 환경을 준비합니다:

Ubuntu 22.04 LTS 서버
Node.js (버전 20 이상) 및 npm (또는 Yarn)
Git (프로젝트 클론 및 형상관리에 필요)
PostgreSQL 데이터베이스 (Medusa 기본 DB)
Redis 서버 (캐싱, 세션, 이벤트용)
MinIO 서버 (상품 이미지 등 파일 저장용 객체 스토리지)

이하에서는 순서대로 각 구성 요소를 설치하고 설정하는 방법을 다룹니다.

1. Node.js 설치 (Ubuntu 22.04)

Ubuntu 22.04에는 기본 저장소에 Node.js가 포함되어 있으나, Medusa 최신 버전을 위해 Node.js 20.x 이상을 권장합니다. NodeSource의 공식 PPA를 통해 Node.js 20을 설치할 수 있습니다:

# NodeSource 저장소 추가 및 Node.js 20 설치
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -  
sudo apt install -y nodejs

위 명령은 NodeSource의 Node.js 20.x 패키지를 등록하고 Node.js를 설치합니다. 설치 후 node -v 및 npm -v로 버전을 확인합니다. 또한 npm은 Node.js 설치 시 함께 포함되므로 별도 설치가 필요 없습니다. (선택적으로 Yarn을 쓰고 싶다면 npm install -g yarn으로 Yarn을 전역 설치합니다.)

2. PostgreSQL 설치 및 설정

Medusa는 기본 데이터베이스로 PostgreSQL을 사용하므로, 서버에 PostgreSQL을 설치합니다:

# PostgreSQL 및 추가 도구 설치
sudo apt update && sudo apt install -y postgresql postgresql-contrib

설치 후 PostgreSQL 서버가 실행 중인지 확인한 다음, Medusa용 데이터베이스와 사용자를 만들어줍니다:

# postgres 계정으로 PostgreSQL 쉘 접속
sudo -i -u postgres
psql

-- 데이터베이스 및 사용자 생성 (예: DB명 [Medusa](/medusa), 사용자 [Medusa](/medusa)user)
CREATE DATABASE [Medusa](/medusa);
CREATE USER [Medusa](/medusa)user WITH ENCRYPTED PASSWORD '사용할비밀번호';
GRANT ALL PRIVILEGES ON DATABASE [Medusa](/medusa) TO [Medusa](/medusa)user;
\q

# postgres 계정 종료
exit

위 예시에서는 데이터베이스 이름을 [Medusa](/medusa), 사용자명을 [Medusa](/medusa)user (비밀번호는 사용할비밀번호로 가정)로 생성하였습니다. 생성한 DB 정보는 나중에 Medusa 백엔드 환경변수에 설정하게 됩니다. 참고로, PostgreSQL 설치 직후에는 리눅스 postgres 계정으로 전환하여 데이터베이스를 생성하며, \q로 psql 쉘을 종료합니다.

3. Redis 설치 및 실행

Medusa는 Redis를 캐시, 세션 저장 및 이벤트/작업 큐 등 용도로 활용합니다. Ubuntu에서 Redis를 설치하고 서비스를 시작하는 방법은 다음과 같습니다:

# Redis 서버 설치
sudo apt install -y redis

# Redis 서비스 시작 및 부팅 시 활성화
sudo systemctl start redis
sudo systemctl enable redis

위와 같이 설치하면 Redis 서버가 로컬에서 기본 포트 6379로 실행됩니다. 이후 Medusa 백엔드 설정에서 REDIS_URL로 Redis 연결 정보를 지정하게 됩니다.

4. MinIO 설치 및 설정 (파일 스토리지)

Medusa에서 상품 이미지 등의 파일 업로드를 위해 파일 서비스(file service) 플러그인이 필요합니다. 여기서는 자체 호스트형 객체 스토리지인 MinIO를 사용하여 S3 호환 파일 스토리지를 구축합니다.

MinIO 서버 설치: MinIO의 공식 가이드를 따라 Ubuntu에 맞는 방법으로 MinIO를 설치합니다. (예를 들어, MinIO 공식 웹사이트의 Linux용 서버 바이너리를 다운로드하여 /usr/local/bin에 배치하고 실행 권한을 주는 방식 등을 사용할 수 있습니다. 자세한 내용은 MinIO 문서를 참고하세요.) 설치 후 MinIO 서버를 실행하여 백그라운드에서 상시 동작하도록 설정합니다. 중요: 기본 설정으로 MinIO는 포트 9000을 사용하지만, 이는 Medusa 백엔드의 기본 포트와 충돌하므로 MinIO 서버 포트를 다른 값(예: 9001)으로 변경해야 합니다. 예를 들어 MinIO를 수동 실행한다면 다음과 같이 지정합니다:

minio server /data/minio --console-address ":9090" --address ":9001"

위 명령은 MinIO 서버를 데이터 디렉토리 /data/minio로 구동하면서, API 포트를 9001로 (웹 콘솔은 9090으로) 설정하는 예입니다. 운영 환경에서는 systemctl을 이용해 MinIO를 서비스로 등록하고 재부팅시 자동 시작되도록 구성하는 것을 권장합니다.

버킷 생성 및 접근 설정: MinIO 설치 후 웹 콘솔(http://<서버IP>:9090)에 접속하여 Bucket을 하나 생성합니다. 예를 들어 버킷 이름을 [Medusa](/medusa)로 생성하고, Access Policy(접근 정책)를 “Public”으로 설정합니다. (공개 버킷으로 설정하면 누구나 접근 가능하므로 민감한 데이터를 저장하지 않도록 주의합니다.) 생성한 버킷은 Medusa에서 상품 이미지 등의 저장 공간으로 사용됩니다.

이어서 MinIO 콘솔의 Access Keys 메뉴에서 새 액세스 키를 생성(Create Access Key) 하여 Access Key와 Secret Key 한 쌍을 발급받습니다. 이 키 값들은 Medusa 백엔드가 MinIO에 접근하도록 설정하는 데 사용됩니다. (Secret Key는 생성 직후에만 확인 가능하므로 별도로 안전하게 저장해 두세요.)

Medusa에 MinIO 연동: Medusa 백엔드에서 MinIO를 파일 저장으로 사용하려면 Medusa MinIO 플러그인을 설치하고 설정해야 합니다. Medusa 프로젝트 디렉토리에서 다음 명령을 실행해 플러그인을 추가합니다:

npm install [Medusa](/medusa)-file-minio   # (또는 yarn add [Medusa](/medusa)-file-minio)

설치 후, Medusa 백엔드의 환경설정 파일(.env)에 MinIO 관련 설정을 추가합니다:

# [Medusa](/medusa) .env 설정 예시
MINIO_ENDPOINT=http://localhost:9001        # MinIO 서버 URL (포트 9001)
MINIO_BUCKET=[Medusa](/medusa)                         # 버킷명 (위에서 생성한 버킷)
MINIO_ACCESS_KEY=<발급받은 Access Key>      # MinIO 액세스 키
MINIO_SECRET_KEY=<발급받은 Secret Key>      # MinIO 시크릿 키
# (선택 사항) private bucket 설정 등 추가 옵션 가능

또한 Medusa 백엔드의 설정 파일([Medusa](/medusa)-config.ts 또는 [Medusa](/medusa)-config.js)에서 플러그인 설정을 추가해야 합니다. 예를 들어 [Medusa](/medusa)-config.js 파일의 plugins 배열에 다음을 포함시킵니다:

const plugins = [
  // ... 기존 플러그인들 ... 
  {
    resolve: '[Medusa](/medusa)-file-minio',
    options: {
      endpoint: process.env.MINIO_ENDPOINT,
      bucket: process.env.MINIO_BUCKET,
      access_key_id: process.env.MINIO_ACCESS_KEY,
      secret_access_key: process.env.MINIO_SECRET_KEY,
      // (선택) private_bucket 등 추가 옵션 설정 가능
    },
  },
];

위와 같이 설정하면 Medusa 상품 등의 이미지 업로드 시 해당 파일들이 MinIO 버킷에 저장되며, Admin에서 이미지를 업로드하거나 조회할 수 있게 됩니다.

참고: 추후 Next.js Storefront에서 MinIO에 저장된 상품 이미지를 표시하려면, Next.js의 이미지 도메인 설정에 MinIO 호스트(예: 127.0.0.1 또는 서버 IP)를 추가해야 합니다. 그렇지 않으면 Next.js에서 “un-configured host” 에러가 발생할 수 있습니다. 이 설정 방법은 Storefront 설정 절차에서 다시 언급하겠습니다.

5. Medusa 백엔드(코어) 애플리케이션 생성

이제 Medusa 서버 애플리케이션을 설치하겠습니다. Medusa는 공식적으로 제공되는 프로젝트 생성 CLI를 통해 손쉽게 초기 세팅이 가능합니다. 전역으로 Medusa CLI를 설치할 수도 있지만, 여기서는 npx를 사용하여 최신 생성 도구를 실행하겠습니다.

터미널에서 원하는 디렉토리로 이동한 뒤, 아래 명령을 실행합니다:

npx create-[Medusa](/medusa)-app@latest my-[Medusa](/medusa)-store

위 명령에서 my-[Medusa](/medusa)-store는 새 프로젝트 폴더 이름이며, 동시에 이 이름으로 PostgreSQL 데이터베이스도 기본 생성됩니다. 명령 실행 후 프롬프트에 따라 프로젝트 설정을 진행합니다. PostgreSQL 접속 정보(DB 사용자, 비밀번호 등)를 묻는 경우 앞서 생성한 [Medusa](/medusa) DB와 [Medusa](/medusa)user 계정 정보를 입력합니다. 또한 Next.js Storefront 설치 여부를 묻는다면 "Yes"를 선택하여 함께 설치하도록 합니다. (Storefront는 나중에 별도로 추가할 수도 있지만, 여기서 함께 설치하면 편리합니다.)

프롬프트에 답변을 완료하면, 스크립트가 Medusa 백엔드와 Admin 대시보드 코드를 해당 프로젝트 폴더에 설치하고 데이터베이스 초기 설정을 진행합니다. Storefront를 설치하기로 선택했다면, 별도의 폴더에 Next.js 스토어프론트 프로젝트도 자동 생성됩니다. 설치가 성공적으로 끝나면 프로젝트 디렉토리 구조는 다음과 같습니다:

Medusa 프로젝트 구조: my-[Medusa](/medusa)-store 폴더에는 Medusa 백엔드 코드와 Admin 대시보드가 통합되어 있으며, 별도로 생성된 my-[Medusa](/medusa)-store-storefront 폴더에 Next.js 스토어프론트 코드가 위치합니다. 백엔드 프로젝트의 src 디렉토리에는 추후 커스터마이징을 위한 폴더들(admin, api, modules 등)이 포함되어 있습니다.

6. Medusa 서버 실행 및 관리자 초기 설정

Medusa 설치 완료 후, 생성된 프로젝트로 이동하여 개발 서버를 실행합니다. (만약 create-[Medusa](/medusa)-app 명령이 이미 서버를 가동한 상태로 종료되었다면, 일단 Ctrl+C로 중지한 뒤 수동으로 재실행합니다.)

백엔드 프로젝트 디렉토리(my-[Medusa](/medusa)-store)로 이동하여 다음 명령을 실행합니다:

npm run start   # 또는 npm run dev (개발용), Yarn 사용 시 yarn dev

이 명령으로 Medusa 백엔드 서버가 개발 모드로 실행되며, 포트 9000에서 대기합니다. 서버 시작과 함께 Admin 대시보드 빌드가 완료되면 브라우저를 자동 열도록 설정되어 있을 수 있는데, 만약 자동으로 열리지 않으면 수동으로 http://<서버IP>:9000/app 주소에 접속합니다. 그러면 Medusa Admin 대시보드 초기 화면이 나타납니다. (Storefront를 함께 설치한 경우, Storefront 개발 서버도 포트 8000에서 실행되며, 이는 다음 단계에서 다룹니다.)

Admin 사용자 생성: Admin 대시보드에 처음 접속하면 관리자로 로그인하기 위한 계정이 없으므로, 가입 절차를 진행해야 합니다. 화면의 안내에 따라 이메일과 비밀번호를 정해 관리자를 생성합니다. 또는 터미널에서 Medusa CLI 명령을 사용해 계정을 만들 수도 있습니다. 예를 들어 프로젝트 폴더에서 아래 명령을 실행하면:

npx [Medusa](/medusa) user -e admin@[Medusa](/medusa)js.com -p supersecret

위 명령은 해당 이메일과 비밀번호로 관리자 사용자를 추가합니다 (이메일 admin@[Medusa](/medusa)js.com, 비밀번호 supersecret는 원하는 대로 변경 가능). 이렇게 생성한 계정으로 Admin 대시보드에 로그인할 수 있습니다.

환경 변수 설정 확인: 기본적으로 create-[Medusa](/medusa)-app 스크립트가 프로젝트 내 .env 파일을 생성하여 PostgreSQL, Redis 등의 연결 정보를 채워넣습니다. .env 파일을 열어(my-[Medusa](/medusa)-store/.env) 앞서 만든 DB 이름, 사용자, 비밀번호가 제대로 설정되어 있는지 확인하세요. 잘못되어 있다면 다음과 같이 수정합니다 (예시):

DATABASE_URL=postgres://[Medusa](/medusa)user:사용할비밀번호@localhost:5432/[Medusa](/medusa)
REDIS_URL=redis://localhost:6379
MINIO_ENDPOINT=http://localhost:9001
MINIO_BUCKET=[Medusa](/medusa)
MINIO_ACCESS_KEY=<Access Key>
MINIO_SECRET_KEY=<Secret Key>

수정 후 서버를 재시작하면 (Ctrl+C 종료 후 npm run start 재실행), 변경된 설정이 반영됩니다. 데이터베이스 마이그레이션은 설치 과정에서 자동 수행되었지만, 필요할 경우 [Medusa](/medusa) migrations run 명령으로 수동 적용도 가능합니다.

7. Next.js Storefront 설정 및 실행

Storefront를 함께 설치한 경우, my-[Medusa](/medusa)-store-storefront 디렉토리에 Medusa 팀이 제공하는 Next.js 스토어프론트 스타터 코드가 들어있습니다. 이 Storefront는 Medusa 백엔드의 Store API를 이용해 상품 목록, 장바구니, 주문 등 기능을 구현하는 프론트엔드 애플리케이션입니다.

우선 스토어프론트 디렉토리로 이동하여 의존성을 설치합니다:

cd my-[Medusa](/medusa)-store-storefront
npm install

설치 후, 개발 서버를 실행합니다:

npm run dev   # (또는 yarn dev)

정상적으로 실행되면 포트 8000에서 스토어프론트가 구동되며, 브라우저에서 http://<서버IP>:8000으로 접속해 스토어 화면을 확인할 수 있습니다. Storefront는 기본적으로 Medusa 백엔드의 주소(http://localhost:9000)를 알고 있으므로, 동일한 서버에서 구동하는 한 별도 환경변수 설정이 없어도 동작합니다. (원격 또는 다른 도메인에서 백엔드 API를 사용할 경우, NEXT_PUBLIC_[Medusa](/medusa)_BACKEND_URL 환경변수를 설정해야 합니다.)

Storefront 이미지 도메인 설정: 앞서 설정한 대로 MinIO를 통해 상품 이미지를 관리하는 경우, Next.js에서 외부 이미지 도메인 설정을 추가해야 합니다. Next.js의 next.config.js 파일을 열어 이미지 설정에 MinIO 호스트를 허용 도메인으로 추가합니다. 예를 들어 개발 환경에서 MinIO가 동일 서버의 127.0.0.1:9001로 동작 중이라면:

// next.config.js (일부 발췌)
module.exports = {
  // ... 기존 설정 ...
  images: {
    remotePatterns: [
      // 기타 도메인 패턴들 ...
      {
        protocol: "http",
        hostname: "127.0.0.1",  // 또는 MinIO 서버 IP/도메인
      },
    ],
  },
};

이 설정을 적용해야 Next.js가 MinIO에서 오는 상품 이미지 URL을 신뢰하고 로딩할 수 있습니다. 설정 후 스토어프론트 개발 서버를 재시작하면(Admin에서 업로드한 상품 이미지가 Storefront에 정상 표시될 것입니다).

Git 저장소 구성 전략 (모노레포 vs 멀티레포)

Medusa 기반 프로젝트를 개발할 때 Git 저장소 구조를 어떻게 가져갈지 결정해야 합니다. 기본적으로 Medusa 백엔드(및 Admin)와 Storefront는 분리된 프로젝트로 제공됩니다. 분리된 구성은 각 부분을 독립적으로 관리하고 배포할 유연성을 주지만, 반대로 하나의 리포지토리(monorepo)에서 관리하면 관련된 변경을 한 곳에서 추적하고 일괄 관리하기가 수월해집니다.

모노레포 접근: Medusa 백엔드(+Admin)와 Storefront 코드를 한 개의 저장소에 넣어 관리하면, 예를 들어 백엔드 API 수정과 프론트 수정이 동시에 커밋되어 형상 관리될 수 있고, 통합 CI/CD 파이프라인을 구축하기에도 편리합니다. 모노레포에서는 폴더 구조를 정하여, 예를 들어 루트에 backend/ (Medusa 백엔드)와 storefront/ (Next.js 프론트) 디렉토리를 두고 각각의 package.json을 관리하는 방식으로 구성할 수 있습니다. Yarn Workspaces나 Lerna 등을 활용하면 의존성 관리도 통합할 수 있습니다.

멀티레포 접근: 백엔드와 프론트를 별도 저장소로 분리하면 배포주기나 협업 팀이 완전히 분리된 경우에 유용할 수 있습니다. 예를 들어 백엔드(Medusa) 팀과 프론트(스토어프론트) 팀이 다를 때 소스 히스토리가 섞이지 않고 관리되는 장점이 있습니다. 하지만 변경의 추적이나 환경 설정(sync)이 번거로울 수 있고, 의존된 변경을 동기화하는 데 유의해야 합니다.

Git 서브모듈 사용: 서브모듈은 한 저장소 안에 다른 저장소를 포함시키는 방법으로, Medusa 공식 Admin 혹은 Storefront 코드를 끌어오는 데 쓸 수도 있습니다. 그러나 일반적인 프로젝트 개발 단계에서는 서브모듈은 추가적인 복잡성을 야기할 수 있습니다. Medusa 팀의 가이드에서도 모노레포로 구성할 경우 서브모듈이 아니라 각각의 프로젝트를 독립 폴더로 클론하고 .git 폴더를 제거해 하나의 저장소로 통합하는 방법을 권장합니다. 실제로 Medusa 공식 Admin 패널을 모노레포에 포함시키는 예제에서, git clone으로 admin 코드를 가져온 뒤 .git 폴더를 삭제함으로써 서브모듈이 아닌 모노레포의 일부로 만드는 과정을 보여줍니다. 이처럼 서브모듈은 특별한 필요가 없는 한 지양하고, 대신 Git Subtree나 패키지 형태의 통합을 고려할 수도 있습니다.

권장 방식: 대부분의 경우 모노레포 구성을 권장합니다. Two-Weeks-Team과 같은 팀 조직의 GitHub를 사용한다면, 하나의 리포지토리에서 backend와 storefront를 함께 관리하되, 필요에 따라 디렉토리별로 서로 다른 배포 파이프라인을 구축할 수 있습니다. 예를 들어 같은 리포지토리 안에서 backend/ 디렉토리 변경시에는 백엔드 서버를 배포하고, storefront/ 디렉토리 변경시에는 프론트 애플리케이션을 배포하는 식입니다. 이렇게 하면 백엔드와 프론트의 코드 변경을 한눈에 추적할 수 있으며, 의존 관계가 있는 변경(commit)을 일관되게 관리할 수 있습니다.

반대로, 백엔드/프론트를 완전히 별도로 운영하거나 오픈소스 프로젝트와 동기화해야 하는 경우에는 멀티레포도 고려할 수 있습니다. 이 경우 각 리포지토리에 공통의 변경사항(예: API 스키마 변경)은 명확히 문서화하고 관리해야 합니다.

결론적으로, 소규모 팀이나 동일한 주기로 개발되는 프로젝트라면 모노레포로의 통합을 통해 개발 경험을 향상시킬 수 있으며, Medusa 자체도 이러한 구성을 지원합니다. 다만 모노레포로 구성할 때는 앞서 언급한 대로 각 하위 프로젝트의 .git 폴더 처리, 워크스페이스 구성 등에 주의하여 설정하면 됩니다.

Amazon 마켓플레이스 연동 모듈 개발 (주문/재고 동기화)

현대적인 이커머스에서는 자사 스토어뿐 아니라 아마존과 같은 마켓플레이스를 통한 판매 채널을 병행하는 경우가 많습니다. Medusa의 모듈식 아키텍처를 활용하면, Amazon 마켓플레이스 연동 모듈을 개발하여 한 백엔드에서 여러 채널의 데이터와 주문을 통합 관리할 수 있습니다.

Medusa Sales Channel Module(판매채널 모듈)을 사용하면 제품을 판매 채널별로 구분하여 재고 및 노출을 관리할 수 있습니다. Amazon을 하나의 Sales Channel로 정의해두고, 그 채널에만 유효한 상품이나 재고를 설정할 수 있습니다. 그 다음, Amazon Seller Central(판매자 프로그램)의 API와 통신하는 커스텀 모듈을 작성하여 Amazon 마켓플레이스와 Medusa 간 데이터를 동기화합니다.

구현 개요:

Medusa에서 Sales Channel Module을 활성화하고 Amazon용 채널을 생성합니다 (예: 채널 코드 "amazon"). 이렇게 하면 특정 상품을 Amazon 채널에 할당하거나 Amazon 주문을 별도로 구분할 수 있는 기반이 마련됩니다.
Amazon 연동 모듈(예: AmazonModule)을 Medusa의 커스텀 모듈로 개발합니다. 이 모듈에서는 Amazon의 Selling Partner API를 호출하여 상품 등록, 재고 조회/수정, 주문 조회 등을 수행합니다. Amazon API 인증을 위해 필요한 자격증명(Access Key, Secret, OAuth 토큰 등)을 모듈 설정에 포함시켜 두어야 합니다.
Medusa의 워크플로우(Workflows)와 스케줄링(Job) 기능을 활용하여 정기 동기화 작업을 구현합니다. 예를 들어 재고 동기화의 경우 Medusa에서 재고 변화 이벤트가 발생할 때 Amazon API로 해당 상품 재고를 업데이트하거나, 일정 주기마다 Medusa 재고와 Amazon 재고를 비교/조정하는 작업을 스케줄링할 수 있습니다. 주문 동기화의 경우 Amazon 주문 API를 주기적으로 폴링(polling)하거나 Amazon의 웹훅/이벤트를 활용하여, 새 주문을 Medusa에 자동 생성하는 흐름을 만들 수 있습니다. 이를 위해 Medusa의 Workflow 엔진을 사용해 Amazon 주문 수집 → Medusa Order 생성 → 재고 차감 등의 일련의 과정을 구현할 수 있습니다.
Medusa의 이벤트/구독(Subscriber) 시스템으로 Amazon 연동을 강화할 수도 있습니다. Medusa에서 주문 생성이나 재고 변경 이벤트가 발생하면 Amazon 모듈의 핸들러가 이를 받아 Amazon API로 전송하거나, 반대로 Amazon 쪽에서 받아온 이벤트를 Medusa API 호출로 처리하는 식입니다.

Medusa 문서의 옴니채널 커머스 예시에서도 “Sales Channel Module로 제품 가용 범위를 채널별로 설정하고, 커스텀 모듈에서 Amazon 판매자 프로그램과 통합하여 제품과 주문을 동기화”하는 방식을 권장하고 있습니다. 이 방식으로 구현하면, Medusa Admin에서 Amazon 채널의 주문과 재고를 한눈에 관리할 수 있고, 제품 정보도 일관되게 유지할 수 있습니다. 예를 들어 Admin 대시보드에서 Amazon 채널의 주문을 조회하고 처리하거나, 한 상품의 재고를 자사몰과 Amazon에 동시에 업데이트하는 것이 가능해집니다.

구현 시 고려사항: Amazon Selling Partner API는 비교적 복잡하고 제한된 쿼타가 있으므로, 동기화 주기를 적절히 조절하고 오류 처리 및 예외 상황(예: 상품 정보 불일치 시 조정 로직)을 잘 설계해야 합니다. 또한 Medusa의 확장성에 맞게 모듈을 분리된 패키지로 개발하여 유지보수하는 것이 좋습니다 (예: [Medusa](/medusa)-module-amazon 형태로 별도 리포지토리/패키지화). Medusa 2.0부터는 모듈 간 격리와 링크(Link) 개념이 도입되어, 기존 코어를 포크하지 않고도 독립 모듈로 원하는 통합을 구현할 수 있으므로 이를 적극 활용합니다.

마지막으로, Amazon 연동 모듈의 개발이 완료되면, Admin 대시보드 커스터마이징을 통해 Amazon 채널의 주문이나 상품에 특화된 UI를 추가할 수도 있습니다. Medusa Admin은 플러그인 형태로 위젯이나 페이지를 추가할 수 있으므로, 예를 들어 “Amazon 주문 동기화” 버튼이나 대시보드 위젯을 만들어 관리자가 수동 동기화를 트리거하거나 현황을 볼 수 있게 하면 편의성이 높아집니다.

以上와 같은 접근으로 Medusa를 기반으로 한 자체 스토어와 Amazon 마켓플레이스를 효과적으로 통합할 수 있습니다. 여러 판매 채널의 재고, 주문을 한 시스템에서 관리함으로써 옴니채널 커머스 운영을 구현할 수 있으며, 이는 Medusa의 지향점 중 하나이기도 합니다.

결론

이상으로 Ubuntu 22.04 서버에 Medusa를 스탠드얼론으로 설치하여 백엔드(Core)와 필수 서비스(PostgreSQL, Redis, MinIO 등)를 구성하고, Admin 대시보드 및 Next.js Storefront를 설정하는 방법을 살펴보았습니다. 또한 코드베이스 관리를 위한 Git 리포지토리 구성 전략과, Medusa의 모듈 시스템을 활용한 Amazon 마켓플레이스 연동 방안도 개략적으로 소개하였습니다.

Medusa는 유연한 모듈 아키텍처와 풍부한 REST API 덕분에, 기본 기능 이상으로 다양한 서드파티 연동과 커스터마이징이 가능합니다. 이 가이드를 통해 구축한 환경을 기반으로, 필요에 맞게 새로운 모듈을 추가하거나 Admin/UI를 확장하면서 자신만의 커머스 백엔드를 만들어 나갈 수 있을 것입니다. 설치 과정에서 언급한 참고 문헌과 Medusa 공식 문서를 수시로 참조하면 문제 해결과 고급 기능 구현에 큰 도움이 됩니다. 원활한 개발과 운영을 기원합니다!

참고 문헌: Medusa 공식 문서 및 블로그 (Installation Guide, Architecture, Deployment Guide), Therichpost Medusa 설치 가이드, Medusa Omnichannel Recipe, Medusa 모노레포 안내 블로그 등.

메두사(Medusa) 스탠드얼론 설치 가이드 (Ubuntu 22.04, Docker 미사용)

메두사(Medusa) 스탠드얼론 설치 가이드 (Ubuntu 22.04, Docker 미사용)

소개 (Medusa란?)

Medusa 아키텍처 개요 및 구성 요소

설치 전제조건 및 환경 준비

1. Node.js 설치 (Ubuntu 22.04)

2. PostgreSQL 설치 및 설정

3. Redis 설치 및 실행

4. MinIO 설치 및 설정 (파일 스토리지)

5. Medusa 백엔드(코어) 애플리케이션 생성

6. Medusa 서버 실행 및 관리자 초기 설정

7. Next.js Storefront 설정 및 실행

Git 저장소 구성 전략 (모노레포 vs 멀티레포)

Amazon 마켓플레이스 연동 모듈 개발 (주문/재고 동기화)

결론

메모장 링크

연결된 문서:

최근 변경

목차

최근 변경