메두사 스탠드얼론 설치 가이드: 도커 없이 완벽 설정하기
최근 수정 시각: 2025-09-03 19:30:44
개요
메두사(Medusa.js)는 Node.js 기반의 헤드리스 이커머스 플랫폼으로, Shopify의 대안으로 각광받고 있는 오픈소스 솔루션입니다[1][2]. 이 가이드에서는 도커를 사용하지 않고 스탠드얼론 방식으로 메두사를 설치하는 전체 과정을 단계별로 설명합니다.
시스템 요구사항
메두사를 성공적으로 설치하기 위해서는 다음 시스템 요구사항을 충족해야 합니다[3][4] :
필수 소프트웨어
| 소프트웨어 | 최소 버전 | 권장 버전 | 용도 |
|---|---|---|---|
| Node.js | 16+ | 18+ LTS | 런타임 환경 |
| PostgreSQL | 9.6+ | 14+ | 메인 데이터베이스 |
| Redis | 5+ | 7+ | 캐싱 및 세션 관리 |
하드웨어 요구사항
| 환경 | RAM | CPU | 저장공간 | 포트 |
|---|---|---|---|---|
| 개발 환경 | 4GB | 2 Core | 20GB | 9000, 5432, 6379 |
| 운영 환경 | 8GB | 4 Core | 40GB | 9000, 5432, 6379 |
단계별 설치 과정
1단계: Node.js 설치
Node.js는 메두사의 핵심 런타임 환경입니다. LTS(Long Term Support) 버전 사용을 권장합니다[5][6].
Windows에서 Node.js 설치
# 공식 웹사이트에서 다운로드
# https://nodejs.org에 접속하여 LTS 버전 다운로드
# 설치 후 버전 확인
node --version
npm --versionmacOS에서 Node.js 설치
# Homebrew 사용 (권장)
brew install node
# 또는 fnm 사용 (버전 관리 도구)
brew install fnm
fnm install --lts
fnm use lts-latestLinux(Ubuntu/Debian)에서 Node.js 설치
# NodeSource repository 추가
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# Node.js 설치
sudo apt-get install -y nodejs
# 버전 확인
node --version
npm --version2단계: PostgreSQL 설치 및 설정
PostgreSQL은 메두사의 주요 데이터 저장소 역할을 합니다[7][8].
Windows에서 PostgreSQL 설치
# 공식 웹사이트에서 설치 프로그램 다운로드
# https://www.postgresql.org/download/windows/
# 설치 과정에서 다음 정보 기록:
# - 슈퍼유저 비밀번호
# - 포트 번호 (기본값: 5432)Linux에서 PostgreSQL 설치
# 패키지 업데이트 및 설치
sudo apt update
sudo apt install postgresql postgresql-contrib
# PostgreSQL 서비스 시작
sudo systemctl start postgresql
sudo systemctl enable postgresql
# PostgreSQL 버전 확인
sudo -u postgres psql -c "SELECT version();"데이터베이스 및 사용자 생성
-- PostgreSQL 콘솔 접속
sudo -u postgres psql
-- 메두사용 데이터베이스 생성
CREATE DATABASE medusa_store;
-- 메두사용 사용자 생성
CREATE USER medusa_user WITH PASSWORD 'your_secure_password';
-- 권한 부여
GRANT ALL PRIVILEGES ON DATABASE medusa_store TO medusa_user;
ALTER USER medusa_user CREATEDB;
-- 연결 확인
\q3단계: Redis 설치 및 설정
Redis는 세션 관리와 캐싱을 위해 필요합니다[9][10].
Linux에서 Redis 설치
# 패키지 설치
sudo apt update
sudo apt install redis-server
# 설정 파일 편집
sudo nano /etc/redis/redis.conf
# 다음 설정 변경:
# supervised no → supervised systemd
# # requirepass foobared → requirepass your_redis_password
# Redis 서비스 재시작
sudo systemctl restart redis-server
sudo systemctl enable redis-server
# 연결 테스트
redis-cli ping
# 응답: PONGRedis 스탠드얼론 설정
# 설정 파일 생성
vi ~/redis.conf
# 기본 설정 내용
port 6379
daemonize yes
protected-mode yes
dir "/home/redis/data/"
dbfilename medusa.rdb
appendfilename medusa.aof
logfile /home/redis/logs/redis.log
requirepass your_redis_password4단계: 메두사 애플리케이션 생성
# 프로젝트 디렉토리 생성
mkdir my-ecommerce-store
cd my-ecommerce-store
# 메두사 애플리케이션 생성
npx create-medusa-app@latest my-medusa-store
# 설치 과정에서 다음 선택:
# - PostgreSQL 데이터베이스 선택
# - Next.js 스토어프론트 설치 여부 선택
# - 관리자 이메일 입력설치가 성공하면 다음과 같은 디렉토리 구조가 생성됩니다[11][12] :
my-medusa-store/
├── src/
│ ├── admin/ # 관리자 대시보드 커스터마이징
│ ├── api/ # 커스텀 API 라우트
│ ├── jobs/ # 스케줄링된 작업
│ ├── modules/ # 커스텀 모듈
│ └── workflows/ # 커스텀 워크플로우
├── medusa-config.ts # 메두사 설정 파일
├── .env # 환경 변수 파일
└── package.json # 프로젝트 의존성5단계: 환경 변수 설정
.env 파일을 생성하고 다음 설정을 추가합니다[13] :
# 데이터베이스 설정
DATABASE_URL=postgres://medusa_user:your_secure_password@localhost:5432/medusa_store
# Redis 설정
REDIS_URL=redis://:your_redis_password@localhost:6379
# JWT 및 쿠키 시크릿
JWT_SECRET=your_jwt_secret_key_here
COOKIE_SECRET=your_cookie_secret_key_here
# CORS 설정
ADMIN_CORS=http://localhost:9000,http://localhost:7001
STORE_CORS=http://localhost:8000
# 서버 설정
PORT=90006단계: 데이터베이스 마이그레이션 실행
# 메두사 프로젝트 디렉토리로 이동
cd my-medusa-store
# 데이터베이스 마이그레이션 실행
npx medusa migrations run
# 샘플 데이터 생성 (선택사항)
npx medusa seed -f data/seed.json7단계: 개발 서버 실행
# 개발 서버 시작
npx medusa develop
# 또는 개발 모드로 실행
npm run dev성공적으로 실행되면 다음 서비스들이 시작됩니다[11][12] :
- 메두사 API 서버: http://localhost:9000
- 관리자 대시보드: http://localhost:9000/app
메두사 설치 단계별 예상 소요시간
8단계: 관리자 사용자 생성
CLI를 통해 관리자 사용자를 생성할 수 있습니다[11] :
# 관리자 사용자 생성
npx medusa user create --email [email protected] --password your_admin_password
# 또는 대화형 모드
npx medusa user create9단계: Next.js 스토어프론트 설치 (선택사항)
메두사와 함께 사용할 Next.js 스토어프론트를 별도로 설치할 수 있습니다:
# 새 터미널에서 스토어프론트 설치
npx create-next-app@latest my-medusa-storefront --use-npm --app
cd my-medusa-storefront
# 메두사 JavaScript SDK 설치
npm install @medusajs/medusa-js
# 개발 서버 시작 (포트 8000)
npm run dev설정 파일 상세 분석
medusa-config.ts 파일 구성
import { defineConfig } from '@medusajs/medusa'
export default defineConfig({
projectConfig: {
// 데이터베이스 설정
database_url: process.env.DATABASE_URL,
database_type: 'postgres',
// Redis 설정
redis_url: process.env.REDIS_URL,
// CORS 설정
store_cors: process.env.STORE_CORS,
admin_cors: process.env.ADMIN_CORS,
// JWT 설정
jwt_secret: process.env.JWT_SECRET,
cookie_secret: process.env.COOKIE_SECRET,
},
// 플러그인 설정
plugins: [
{
resolve: '@medusajs/medusa/dist/plugins/cache-redis',
options: {
redisUrl: process.env.REDIS_URL,
},
},
{
resolve: '@medusajs/file-local',
options: {
upload_dir: 'uploads',
},
},
],
})문제 해결 및 디버깅
일반적인 설치 오류
포트 충돌 문제
# 사용 중인 포트 확인
netstat -tulpn | grep :9000
lsof -i :9000
# 프로세스 종료
kill -9 <PID>데이터베이스 연결 오류
# PostgreSQL 서비스 상태 확인
sudo systemctl status postgresql
# 연결 테스트
psql -h localhost -U medusa_user -d medusa_storeRedis 연결 오류
# Redis 서비스 상태 확인
sudo systemctl status redis-server
# Redis CLI 연결 테스트
redis-cli -a your_redis_password ping로그 확인 방법
# 메두사 서버 로그 확인 (개발 모드)
npx medusa develop --verbose
# PostgreSQL 로그 확인
sudo tail -f /var/log/postgresql/postgresql-*.log
# Redis 로그 확인
sudo tail -f /var/log/redis/redis-server.log성능 최적화 설정
PostgreSQL 최적화
-- postgresql.conf 파일 수정
shared_buffers = 256MB
work_mem = 6553kB
effective_cache_size = 768MB
maintenance_work_mem = 64MB
max_connections = 100Redis 최적화
# redis.conf 설정
maxmemory 4294967296 # 4GB
maxmemory-policy allkeys-lru
tcp-keepalive 300
timeout 0보안 고려사항
환경 변수 보안
# .env 파일 권한 설정
chmod 600 .env
# Git에서 제외
echo ".env" >> .gitignore데이터베이스 보안
-- 강력한 비밀번호 설정
ALTER USER medusa_user PASSWORD 'complex_password_123!@#';
-- 불필요한 권한 제거
REVOKE ALL ON SCHEMA public FROM PUBLIC;
GRANT USAGE ON SCHEMA public TO medusa_user;배포 준비
프로덕션 빌드 생성
# 프로덕션 빌드
npx medusa build
# 빌드 결과물 확인
ls -la .medusa/프로덕션 환경 변수
# .env.production 파일 생성
NODE_ENV=production
DATABASE_URL=your_production_database_url
REDIS_URL=your_production_redis_url
JWT_SECRET=your_production_jwt_secret
COOKIE_SECRET=your_production_cookie_secret전체 요약
메두사 스탠드얼론 설치는 총 10단계로 구성되며, 예상 소요시간은 약 70분, 평균 난이도는 1.8/5 수준입니다.
주요 성공 요인:
- 시스템 요구사항 철저한 확인 - Node.js 16+, PostgreSQL 9.6+, Redis 5+ 버전 준수[3][4]
- 단계별 순서 준수 - 의존성 순서에 따른 설치 진행[11][12]
- 환경 변수 정확한 설정 - 데이터베이스 및 Redis 연결 정보 정확 입력[13]
- 보안 설정 적용 - 강력한 비밀번호 및 적절한 권한 설정[7]
이 가이드를 따라 진행하면 도커 없이도 완전한 기능을 갖춘 메두사 이커머스 플랫폼을 성공적으로 구축할 수 있습니다. 각 단계별 예상 소요시간과 주요 작업을 참고하여 계획적으로 설치를 진행하시기 바랍니다.
[↑] [12] https://medusajs.com