🚀 macOS 및 Linux에서 Magento + Warden + Hyvä를 가장 빠르게 설정하는 방법 (mage-mirror 소개)

Source: Dev.to

Magento 2 환경을 새로 설정하거나 — 프로덕션 스토어를 복제해 로컬에서 디버깅하려고 — 시도해 본 적이 있다면 다음과 같은 고통을 잘 알고 있을 것입니다:

• 설치 시간이 오래 걸림
• Composer 설정 중 패키지 실패
• OpenSearch 오류
• Warden 버전 불일치
• PHP 확장 모듈 누락
• 관리자 로그인 문제
• 업그레이드 리허설이 느림

같은 환경 설정 단계를 수년간 반복한 뒤, 저는 mage‑mirror를 만들었습니다 — 한 번의 명령으로 Magento + Warden + Hyvä를 설치해 주는 도구입니다.

GitHub:

2 분 안에 mage‑mirror는 다음을 포함한 완전한 Magento 환경을 구축합니다:

• Magento 2.4.x
• Warden (Docker) 스택
• Hyvä 테마 (선택 사항)
• 샘플 데이터 (선택 사항)
• 멀티‑스토어 라우팅
• Composer 설정
• OpenSearch 자동 수정
• 관리자 자동 생성
• 원격 동기화 및 복제
• 업그레이드 모드

실행은 다음과 같이 간단합니다:

./_mage-mirror.sh

…그리고 끝—Magento가 바로 준비됩니다.

왜 Magento 로컬 개발은 아직도 어려운가

Magento는 강력하지만 무겁습니다. 로컬 환경을 구축하려면 보통 다음과 같은 작업이 필요합니다:

• PHP + Composer + MySQL을 수동으로 설치
• 권한 문제 해결
• OpenSearch 고치기
• Composer가 끝날 때까지 20~40분 대기
• 인덱스 재생성
• 암호 키 트러블슈팅
• 설정 패치
• 스토어와 스코프 생성

Magento를 전문적으로 다루는 경우, 낭비되는 시간이 금방 쌓입니다. Hyvä는 프론트엔드 개발을 크게 빠르게 해 주지만, 백엔드 환경 설정은 여전히 팀의 병목입니다. 저는 이를 깔끔하게 해결해 줄 도구가 필요했습니다.

mage‑mirror가 자동화하는 것

mage‑mirror는 속도, 반복 가능성, 불편함 제로를 목표로 만들어졌습니다.

1. 한 번의 명령 = 전체 Magento 환경

./_mage-mirror.sh

스크립트가 수행하는 일:

• Warden가 없으면 설치
• Composer로 프로젝트 생성
• Magento 2.4.x 설정
• URL 및 스코프 구성
• 관리자 사용자 생성
• 정적 자산 배포
• DI 컴파일
• 파일 권한 수정
• 샘플 데이터 로드 (선택 사항)

수동 작업 없이 필요한 모든 것이 준비됩니다.

2. Hyvä 테마 자동 설정 (선택 사항)

환경 변수를 설정합니다:

INSTALL_HYVA=yes

mage‑mirror는 Hyvä 테마를 (OSS Composer 미러를 통해) 가져와 설치하고, 스토어프론트로 활성화합니다.

3. 기존 Magento 프로젝트 복제 (로컬 또는 원격)

프로덕션 스토어, 스테이징 환경, 클라이언트 사이트, QA 스냅샷 등을 rsync, tar, 원격 mysqldump, 로컬 SQL 덤프 등으로 복제할 수 있습니다.

USE_RSYNC_MAGENTO=yes
USE_REMOTE_DB_DUMP=yes

스토어가 몇 분 안에 로컬에서 실행됩니다 — 몇 시간이 아니라요.

4. Magento 업그레이드 모드

2.4.x → 2.4.y 업그레이드를 테스트하려면:

UPGRADE_MAGENTO=yes
UPGRADE_MAGENTO_VERSION=2.4.*

mage‑mirror는:

• 기존 스토어를 가져옴
• Composer 버전 제약을 조정
• 전체 Composer 업데이트 실행
• setup:upgrade 수행
• 필요에 따라 인덱스 재생성, 컴파일, 배포, 설정 패치

유지보수 작업에 큰 변화를 줍니다.

5. 멀티‑스토어 라우팅 (사전 구성)

활성화된 경우, mage‑mirror는 자동으로 다음을 매핑합니다:

mage.test      → Website A
app.mage.test  → Website B

/etc/hosts를 업데이트하고, pub/index.php를 패치해 MAGE_RUN_CODE를 설정하며, 기본 URL과 스코프를 구성합니다 — 수동 단계가 전혀 없습니다.

6. OpenSearch 자동 수정 (“No alive nodes found” 오류 해소)

흔히 보는 오류:

Could not validate a connection to OpenSearch. No alive nodes found.

mage‑mirror는 OpenSearch를 자동으로 설정합니다:

catalog/search/engine = opensearch
hostname = opensearch
port = 9200
prefix = magento2

그 후 전체 재인덱스를 트리거해 오류를 없앱니다.

빠른 시작

git clone https://github.com/j-scriptz/mage-mirror
cd mage-mirror
chmod +x _mage-mirror.sh
./_mage-mirror.sh

Magento는 다음 주소에서 실행됩니다:

• (멀티‑스토어가 활성화된 경우)

예시 설정 파일

모든 설정은 _mage-mirror.config에 있습니다.

빠른 Hyvä 설치

INSTALL_HYVA=yes
WITH_SAMPLE_DATA=no
USE_EXISTING_DB=no

프로덕션 스토어 복제

USE_RSYNC_MAGENTO=yes
USE_REMOTE_DB_DUMP=yes
REMOTE_HOST=myserver
REMOTE_PATH=/var/www/magento

업그레이드 모드

UPGRADE_MAGENTO=yes
UPGRADE_MAGENTO_VERSION=2.4.*

mage‑mirror를 사용하면 좋은 사람

• Magento 에이전시
• 프리랜서
• Hyvä 개발자
• Magento 업그레이드 전문가
• 기여자
• 원클릭 설정이 필요한 주니어 개발자
• 표준화된 로컬 환경을 원하는 팀

Magento를 정기적으로 다루는 사람이라면 mage‑mirror가 주당 몇 시간을 절약해 줍니다.

보너스: 무료 Hyvä‑호환 서브카테고리 카드

설정 중에 Jscriptz Subcats 모듈을 자동 설치할 수 있습니다:

→

스토어프론트 UX와 Hyvä 빌드에 유용합니다.

프로젝트를 지원하고 싶으신가요?

mage‑mirror가 시간을 절약해 주었다면, 지원 방법은 다음과 같습니다:

• GitHub 저장소에 스타 달기
• 이슈나 PR 제출
• Magento 커뮤니티에 알리기

GitHub:

마무리 생각

Magento 개발은 복잡하지만, 로컬 환경은 반드시 그럴 필요는 없습니다. mage‑mirror는 반복되는 고통을 없애고, Magento 스토어를 스핀업하거나 복제하는 작업을 다음 명령 하나만으로 가능하게 합니다:

./_mage-mirror.sh