ServBay 환경에서 Craft CMS 설치 및 설정하기

개요

Craft CMS는 강력한 콘텐츠 관리 시스템(CMS)으로, 유연한 콘텐츠 모델링, 직관적인 사용자 인터페이스, 개발자 친화적인 기능으로 인기를 얻고 있습니다. 복잡하고 맞춤화된 웹사이트 구축에 최적화되어 있습니다.

ServBay를 Craft CMS의 로컬 개발 환경으로 사용할 경우, 사전 설정된 PHP, 데이터베이스(예: MySQL 또는 PostgreSQL), 웹 서버(Caddy 또는 Nginx), 내장 Composer와 CLI 도구 등 다양한 이점이 있습니다. 이로 인해 설치 및 설정 과정이 매우 간편해집니다.

이 가이드는 ServBay 환경에서 Craft CMS 프로젝트를 설치하고 설정하는 전체 과정을 자세히 안내합니다.

사전 준비

시작하기 전에 다음 준비사항을 확인하세요:

ServBay 설치 및 실행: macOS에 ServBay가 정상적으로 설치되어 있고, 필요 PHP 버전(Craft CMS의 버전 요구사항은 Craft CMS 공식 문서 참조)과 데이터베이스(일반적으로 MySQL 또는 PostgreSQL) 패키지가 실행 중이어야 합니다. ServBay는 다양한 PHP 버전과 DB를 지원하므로 요구사항에 맞게 손쉽게 전환하고 설정할 수 있습니다.
기본 명령행 조작 숙지: 디렉터리 생성, Composer 실행 등 몇 가지 명령어를 터미널에서 입력해야 합니다.
Composer 이해: Craft CMS는 Composer로 의존성을 관리합니다. ServBay에는 Composer가 내장되어 있지만, composer create-project 명령 실행 방법을 알고 있어야 합니다.

Craft CMS 설치 단계

다음은 ServBay에서 Craft CMS를 설치하고 설정하는 구체적인 절차입니다.

1단계: 프로젝트 디렉터리 만들기

먼저, ServBay의 기본 웹사이트 루트 디렉터리인 /Applications/ServBay/www에 새 프로젝트 폴더를 만듭니다. 이 디렉터리는 ServBay에서 웹 서버의 기본 서비스 폴더로 설정되어 있어 프로젝트를 바로 접근할 수 있습니다.

터미널에서 아래 명령어를 실행하세요:

bash

cd /Applications/ServBay/www
mkdir servbay-craft-app
cd servbay-craft-app

이 명령은 /Applications/ServBay/www 안에 servbay-craft-app이라는 폴더를 생성하고 해당 폴더로 이동합니다.

2단계: Composer로 Craft CMS 프로젝트 생성

ServBay에는 이미 Composer가 내장되어 있으므로, 바로 프로젝트 폴더에서 Composer로 Craft CMS 프로젝트를 생성할 수 있습니다. Craft CMS 공식 설치법도 Composer 사용을 권장합니다.

servbay-craft-app 폴더에서 아래 명령어를 실행하세요:

bash

composer create-project craftcms/craft .

이 명령을 실행하면 최신 Craft CMS와 모든 의존성이 현재 디렉터리(.)로 설치됩니다. Composer 설치가 완료될 때까지 기다립니다.

3단계: 데이터베이스와 유저 생성

Craft CMS는 콘텐츠 및 설정 정보를 저장할 데이터베이스가 필요합니다. ServBay에 내장된 phpMyAdmin 또는 Adminer를 이용해 데이터베이스와 사용자를 만듭니다. 이 가이드에서는 phpMyAdmin을 예로 설명합니다.

ServBay 데이터베이스 관리 도구(phpMyAdmin) 접속
브라우저에서 ServBay 로컬 개발 패널 https://servbay.host/에 접속 후, 패널 내 phpMyAdmin 링크를 클릭해 데이터베이스 관리 도구로 이동합니다.
팁: ServBay의 기본 phpMyAdmin 접속 계정은 대개 root, 비밀번호는 ServBay.dev입니다. 보안을 위해 접속 후 반드시 root 계정의 비밀번호를 변경하거나 새 관리자 계정을 만드는 것이 좋습니다.
데이터베이스 사용자 생성
보안이나 권한 분리를 위해 Craft CMS용 별도의 데이터베이스 사용자를 만드는 것이 모범 사례입니다.
1. 유저 계정 관리 페이지로 이동
  phpMyAdmin 홈 화면 상단 메뉴에서 '사용자 계정'을 클릭합니다.
2. 새 사용자 추가
  '사용자 추가'를 클릭하고 아래 정보를 입력하세요:
  - 사용자명: Craft CMS DB 접속용 예시로 craft_user 추천
  - 호스트명: localhost 또는 로컬 선택(로컬 접속만 허용)
  - 비밀번호: 안전한 비밀번호 입력(예시 password123은 사용 금지, 실환경에서는 강력한 패스워드를 사용, 개발 환경은 테스트에 적합한 간단한 패스워드도 허용)
  - 비밀번호 재입력: 확인 차원에서 다시 입력
  - '데이터베이스 생성 및 권한 부여' 항목에서 '사용자명과 동일한 DB 생성 및 모든 권한 부여' 선택. 이 옵션을 사용하면 이름이 같은 데이터베이스와 사용자에게 모든 권한이 자동 부여됩니다.
  - '모든 권한 부여' 체크박스도 확인할 것
  - 화면 하단의 '실행' 버튼 클릭
이제 craft_user라는 DB 사용자와 데이터베이스가 생성되었고, 필요한 권한도 부여되었습니다.

4단계: 웹 서버 설정(ServBay 사이트 생성)

ServBay의 웹 서버(Caddy 또는 Nginx)가 Craft CMS 프로젝트에 서비스를 제공할 수 있도록, ServBay에서 사이트를 추가해야 합니다.

ServBay 앱 실행
ServBay 애플리케이션을 실행합니다.
새 웹사이트 추가
왼쪽(또는 구버전은 '호스트')의 '사이트' 메뉴에서 '+', 또는 오른쪽 '사이트 추가' 버튼을 클릭해 새 사이트를 추가합니다.
아래 정보를 입력하세요:
- 이름(Name): 예) My Craft Site
- 도메인(Domains): 로컬에서 접속할 주소, 예) servbay-craft.local (ServBay가 로컬 DNS로 자동 세팅)
- 사이트 타입(Type): PHP 선택
- PHP 버전(PHP Version): 사전 준비 단계에서 Craft CMS 호환성 확인한 PHP 버전 선택(ServBay에서 여러 버전 동시 설치/실행 가능)
- 웹사이트 루트(Website Root): 매우 중요 Craft CMS의 공개 파일(index.php)은 프로젝트 디렉터리의 web 하위 폴더에 있습니다. 보안상 웹 루트는 web 폴더(예: /Applications/ServBay/www/servbay-craft-app/web)로 지정해야 하며, 프로젝트 전체가 아니라 반드시 해당 경로로 지정해야 합니다.
설정 저장
입력 후 '저장'을 클릭하면 ServBay가 설정을 반영하며, 사이트 목록에서 새로 추가한 servbay-craft.local 사이트를 확인할 수 있습니다.

5단계: Craft CMS 설치 마법사 실행

이제 브라우저에서 설정한 도메인으로 접속해, Craft CMS 웹 설치 마법사를 실행할 수 있습니다.

설치 페이지 접속
브라우저에서 https://servbay-craft.local/로 이동하면 Craft CMS가 설치되지 않은 상태를 감지해 설치 페이지(https://servbay-craft.local/index.php?p=admin/install)로 자동 이동합니다.
DB 접속 정보 입력
Craft CMS 설치 페이지에서 다음 정보(3단계에서 생성한 DB 정보)를 입력합니다:
- 데이터베이스 서버(Database Server): localhost
- 데이터베이스명(Database Name): craft_user(또는 직접 생성한 DB명)
- 사용자명(Username): craft_user(또는 직접 생성한 사용자명)
- 비밀번호(Password): 3단계에서 설정한 비밀번호
계속하기를 클릭하면 Craft CMS가 DB 연결을 시도하고, 성공시 다음 단계로 이동합니다.
관리자 계정 정보 입력
페이지 안내에 따라 Craft CMS 관리자 계정을 생성하세요. 사용자명, 비밀번호, 이메일을 입력하고, 강력한 비밀번호를 사용하세요.
계속하기 클릭
사이트 기본 정보 설정
사이트 이름 등 기본 정보를 입력합니다.
'설치 완료(Finish Up)' 버튼을 클릭하면 Craft CMS가 데이터베이스 테이블 생성, 설정 파일 작성 등 최종 설정을 완료합니다.
설치가 끝나면 관리 백오피스 로그인 화면으로 이동합니다.

6단계: 초기 설정 및 탐색

관리 백오피스에 로그인 후, 다음과 같은 초기 설정 및 구성을 진행할 수 있습니다:

.env 파일 확인: Craft CMS는 .env로 환경변수를 관리합니다(DB 접속 정보 포함). 설치시 자동 생성되며, 프로젝트 루트(servbay-craft-app/)에서 확인 가능. CRAFT_ENVIRONMENT를 dev로 변경하는 등 추가 설정을 할 수 있습니다.
플러그인 설치: 관리 콘솔 상단의 '플러그인(Plugins)' 메뉴에서 플러그인을 탐색·설치·관리하며 Craft CMS 기능을 확장할 수 있습니다.
콘텐츠 구조 생성: '설정(Settings)'에서 필드, 섹션(Sections), 분류(Categories), 태그(Tags) 등 사이트 구조를 설계할 수 있습니다.
메일 발송 설정: 로컬에서 메일 기능 테스트가 필요하면, ServBay의 Mailpit 또는 Mailhog 사용을 권장합니다. .env 또는 관리콘솔의 메일 설정에서 SMTP로 세팅, 서버주소는 localhost, 포트는 ServBay 패널에서 제공하는 것을 사용합니다.

자주 묻는 질문 (FAQ)

Q: 설치 중 DB 연결 오류가 발생할 때 해결법은?
- A: Craft CMS 설치 시 입력한 DB 서버 주소(localhost), 데이터베이스명, 사용자명, 비밀번호가 phpMyAdmin에서 만든 정보와 정확히 일치하는지 확인하고, ServBay의 DB 서비스(예: MySQL, PostgreSQL)가 실행 중인지 점검하세요.
Q: servbay-craft.local 접속 시 404 또는 빈 페이지가 출력될 때?
- A:
  - ServBay에서 사이트 생성 시 '웹사이트 루트'가 반드시 /Applications/ServBay/www/servbay-craft-app/web로 지정되어있는지 확인하세요(가장 흔한 설정 착오).
  - ServBay의 웹 서버(Caddy 혹은 Nginx), PHP 서비스가 정상 실행 중인지 확인하세요.
  - ServBay 사이트 리스트에서 servbay-craft.local 사이트가 활성화 상태인지 검토하세요.
Q: Composer로 Craft CMS 설치 속도가 느리거나 실패할 때?
- A: 네트워크 불안 또는 Composer 미러 문제일 수 있습니다. 필요 시 Composer의 미러 소스를 국내(예: 알리클라우드, Packagist China)로 전환 시도하세요.
Q: 설치 완료 후 관리 콘솔이나 메인 페이지에서 스타일이 깨지거나 이미지가 안 보일 때?
- A: 보통 파일 권한 문제입니다. ServBay에서 storage, web/cpresources 등의 폴더에 쓰기 권한이 있는지 확인하세요. 일반적으로 ServBay가 자동으로 처리하지만, 문제가 있다면 수동으로 권한을 재설정 하거나 확인하세요.

요약

위 단계들을 따르면 ServBay 로컬 개발 환경에서 Craft CMS 설치 및 설정이 정상적으로 완료됩니다. ServBay를 활용하면 PHP 버전 관리, 데이터베이스 구성, 웹 서버 세팅이 매우 간단해져 CMS 개발에만 집중할 수 있습니다. 이제 Craft CMS의 강력한 콘텐츠 모델링 기능을 활용해 웹사이트나 애플리케이션 개발을 본격적으로 시작해보세요.

ServBay 환경에서 Craft CMS 설치 및 설정하기 ​

개요 ​

사전 준비 ​

Craft CMS 설치 단계 ​

1단계: 프로젝트 디렉터리 만들기 ​

2단계: Composer로 Craft CMS 프로젝트 생성 ​

3단계: 데이터베이스와 유저 생성 ​

4단계: 웹 서버 설정(ServBay 사이트 생성) ​

5단계: Craft CMS 설치 마법사 실행 ​

6단계: 초기 설정 및 탐색 ​

자주 묻는 질문 (FAQ) ​

요약 ​