[오픈소스 기여 도전기 #1] 맨땅에 헤딩: 우커머스 로컬 환경 구축부터 결제 성공까지

지난 글에서 기여할 프로젝트(woocommerce-gateway-stripe)와 타겟 이슈(#4951)를 정했습니다. 이제는 실제로 코드를 수정하고 테스트할 수 있는 로컬 개발 환경(Local Development Environment)을 구축할 차례입니다.

"그냥 git clone 하고 돌리면 되는 거 아니야?"라고 생각했지만, 역시나 오픈소스의 세계는 호락호락하지 않았습니다. 윈도우 WSL(Ubuntu) 환경에서 겪은 우여곡절과 트러블슈팅 기록을 공유합니다.

https://simjaejin.tistory.com/101

[오픈소스 기여 도전기 #1] 12년 차 개발자의 전략적 접근법: 프로젝트 선정부터 이슈 분석까지

 

---

🛠️ 1. 우커머스 코어 & Stripe 플러그인 설치

woocommerce-gateway-stripe는 단독으로 실행되는 것이 아니라, 우커머스(WooCommerce) 플러그인 위에서 동작합니다. 따라서 우커머스 코어 환경부터 먼저 잡아줘야 합니다.

1-1. 필수 패키지 설치 (PHP 8.3 & Composer & Node.js)

최신 우커머스 구동을 위해 안정적인 PHP 8.3 환경과 패키지 매니저들을 설치합니다.

# 1. PHP 8.3 설치
sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.3 php8.3-cli php8.3-common php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip php8.3-mysql

# 2. Composer 설치
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

# 3. Node.js 패키지 매니저 (pnpm) 설치
npm install -g pnpm

1-2. 소스 코드 다운로드 및 빌드

/project/ 디렉토리를 생성하고 우커머스 코어와 Stripe 게이트웨이를 각각 클론(Clone) 받습니다.

mkdir /project/ && cd /project/

# [Core] 우커머스 설치 및 빌드
git clone https://github.com/HomerSim/woocommerce.git
cd woocommerce
pnpm install --frozen-lockfile
pnpm build

# [Plugin] Stripe 게이트웨이 설치
cd /project/
git clone https://github.com/HomerSim/woocommerce-gateway-stripe.git
cd woocommerce-gateway-stripe
composer install
npm install

# 의존성 문제 해결 (Playwright 관련)
npx playwright install-deps
npm run build

1-3. wp-env 설정 (가장 중요! ⭐)

우커머스 코어 개발 환경에서 Stripe 플러그인을 함께 로드하려면 .wp-env.override.json 설정이 필수입니다.

💡 Tip: plugins 배열에 "."(현재 디렉토리, 즉 우커머스 코어)를 반드시 포함해야 합니다. 이걸 빼먹으면 우커머스가 로드되지 않습니다.

파일 경로: /project/woocommerce/.wp-env.override.json

{
  "plugins": [
    ".",
    "/home/wowls5000/project/woocommerce-gateway-stripe"
  ]
}

이제 개발 환경을 실행합니다.

# 실행 (네트워크 오류 시 재시도)
pnpm --filter='@woocommerce/plugin-woocommerce' env:start

# 중지
pnpm --filter='@woocommerce/plugin-woocommerce' env:stop

---

🚨 2. Stripe 테스트 계정 연동 문제 (Troubleshooting I)

환경은 구축됐지만, Stripe 플러그인 설정 페이지에 들어가 보니 제 계정이 아닌 기본 테스트 계정이 연결되어 있었습니다. 당연히 제 대시보드에서는 결제 내역이 보이지 않았죠.

해결책: DB 직접 수정 (Direct DB Update)

UI에서 설정이 잘 안 먹힐 때는 DB를 직접 건드리는 게 가장 확실합니다. wp_options 테이블의 woocommerce_stripe_settings 값을 제 API 키로 강제 업데이트했습니다.

1. MariaDB 접속

docker exec -it <컨테이너ID> /bin/bash
mariadb -u root -p

2. 설정값 업데이트 SQL 실행 워드프레스 설정값은 직렬화(Serialized)되어 저장되므로, 형식을 정확히 맞춰서 UPDATE 해야 합니다.

UPDATE wp_options 
SET option_value = 'a:35:{s:7:"enabled";s:3:"yes"; ... s:20:"test_publishable_key";s:107:"pk_test_내_공개키";s:15:"test_secret_key";s:107:"sk_test_내_비밀키"; ... }' 
WHERE option_name = 'woocommerce_stripe_settings';

이렇게 하니 드디어 제 Stripe 대시보드에 로그가 찍히기 시작했습니다! 🎉

---

🛑 3. wp-env 실행 시 ETIMEDOUT (Troubleshooting II)

잘 되던 환경이 다음날 집에서 다시 실행하니 ETIMEDOUT 에러를 뱉으며 멈췄습니다.

✖ Reading configuration.
AggregateError [ETIMEDOUT]: code: 'ETIMEDOUT', timings: { ... total: 271 }

원인 분석: 한국-미국 간 레이턴시 vs Node.js 타임아웃

Node.js는 IPv4/IPv6 연결 시도 시 기본 타임아웃을 약 250ms로 잡습니다. 그런데 한국에서 미국 서버(wordpress.org)까지 왕복 시간(RTT)만 해도 200~300ms가 걸립니다. 즉, "서버는 정상인데 응답이 늦게 와서 Node.js가 연결을 끊어버린" 상황이었습니다.

해결책: /etc/hosts 강제 매핑

DNS 조회 시간이라도 줄이기 위해 wordpress.org 관련 도메인들을 /etc/hosts에 직접 등록하여 해결했습니다.

1. 현재 IP 확인

curl -I -v https://api.wordpress.org
# (나온 IP 주소 복사)

2. Hosts 파일 수정 (sudo vi /etc/hosts)

# WordPress Development Network Fix
198.143.164.251 api.wordpress.org
198.143.164.250 downloads.wordpress.org
198.143.164.252 wordpress.org

이 설정을 추가하고 나니 wp-env가 거짓말처럼 쌩쌩하게 돌아가기 시작했습니다.

---

🚀 다음 예고: 로직 분석과 웹훅 테스트

이제 로컬에서 결제까지 되는 완벽한 환경을 갖췄습니다. 하지만 저는 우커머스를 다뤄본적이 없기 때문에 코드 분석이 필요 합니다. 

다음 글에서는 코드 분석과 웹훅 테스트 하는 과정을 담아보겠습니다.