ServBay 환경에서 Contao CMS 설치 및 설정 방법

Contao는 중소기업 웹사이트, 포털 또는 복잡한 웹 애플리케이션 구축에 적합한 강력한 오픈소스 콘텐츠 관리 시스템(CMS)입니다. 본 가이드는 macOS 기반의 손쉬운 로컬 Web 개발 환경인 ServBay에서 Contao를 설치하고 구성하는 방법을 단계별로 설명하여, 빠르게 Contao 프로젝트 개발을 시작할 수 있도록 도와드립니다.

ServBay는 PHP, Composer, 데이터베이스 서비스(MySQL/MariaDB, PostgreSQL 등), 웹 서버(Caddy, Nginx, Apache 등)를 통합 제공하여 로컬 개발 환경 구축을 크게 단순화합니다. ServBay를 이용하면 Contao가 요구하는 실행 환경을 손쉽게 준비할 수 있습니다.

Contao란 무엇인가요?

Contao는 PHP 기반의 오픈소스 콘텐츠 관리 시스템(CMS)으로, 사용자 친화적이고 높은 유연성과 강력한 관리 백엔드를 자랑합니다. 세분화된 권한 관리, 버전 관리, 다국어 지원, 반응형 이미지 처리, 모듈형 아키텍처 등 다양한 기능을 제공하며, 확장 설치가 용이해 맞춤형 웹사이트 구축에 적합합니다. Contao는 개발자와 디자이너가 처음부터 새로운 기능을 만들 필요 없이, 안정적인 토대 위에 맞춤형 웹사이트를 구축할 수 있도록 설계되었습니다.

준비 사항

Contao 설치를 시작하기 전에 다음 사항을 확인하세요:

1. ServBay 설치 및 실행: macOS 시스템에 ServBay가 설치되어 있어야 합니다. ServBay가 실행 중이며, Contao가 요구하는 PHP 버전(최신 요구사항은 Contao 공식 문서 참고)과 데이터베이스 서비스(MySQL 또는 MariaDB 등)가 활성화돼 있는지 확인하세요.
2. Composer: ServBay에는 기본적으로 Composer가 내장되어 있어 별도의 설치가 필요 없습니다.
3. 터미널 사용: Composer 명령을 실행하기 위해 터미널을 사용해야 합니다.

Contao 설치 단계

이 섹션에서는 ServBay 환경에서 Contao를 설치 및 설정하는 구체적인 과정을 안내합니다.

1단계: 프로젝트 디렉터리 생성

먼저 ServBay 기본 웹사이트 루트 디렉터리인 /Applications/ServBay/www로 이동한 뒤, Contao 프로젝트용 하위 폴더를 새로 만듭니다.

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

이제 servbay-contao-app 디렉터리에서 Contao를 설치하게 됩니다.

2단계: Composer로 Contao 프로젝트 생성

Contao는 Composer를 통한 설치 및 관리를 권장합니다. ServBay에는 Composer가 내장되어 있으므로, 아래 명령어를 프로젝트 폴더에서 실행하면 Contao 프로젝트를 생성할 수 있습니다:

composer create-project contao/managed-edition .

이 명령어는 Contao Managed Edition의 최신 버전과 필요한 모든 의존성을 현재 디렉터리(.)에 내려받습니다. 네트워크 속도에 따라 시간이 소요될 수 있습니다.

Contao Managed Edition 설명: contao/managed-edition은 Contao의 공식 배포판으로, Contao 핵심과 권장 의존성이 포함된 표준 프로젝트 구조를 제공합니다. 이 방식으로 설치할 경우, Contao 웹사이트의 루트는 프로젝트 폴더 내 web 하위 폴더가 됩니다.

3단계: 데이터베이스 및 사용자 생성

Contao는 콘텐츠 및 설정 저장을 위해 데이터베이스가 필요합니다. ServBay는 phpMyAdmin 또는 Adminer와 같은 편리한 데이터베이스 관리 도구를 제공합니다. 여기서는 phpMyAdmin 사용 예시를 안내합니다:

1. ServBay 기본 제공 phpMyAdmin 접속

   ServBay의 로컬 접근 주소인 https://servbay.host/를 엽니다. 페이지 내 phpMyAdmin 바로가기를 클릭해 데이터베이스 관리 도구에 진입하세요.

2. 데이터베이스 사용자 생성

   Contao 전용 DB 사용자를 새로 만드는 것이 보안상 좋습니다.

   a. 사용자 계정 페이지로 이동

   phpMyAdmin 메인 화면에서 상단 메뉴의 ‘사용자 계정’을 클릭합니다.
   

   b. 새 사용자 추가

   ‘사용자 계정 추가’ 버튼을 눌러 아래 항목을 작성합니다:
   
   *   **사용자명:** Contao DB 연결에 사용할 사용자명을 입력(예: `contao_user`)
   *   **호스트명:** `localhost` 선택(로컬 연결만 허용되어 보안 강화)
   *   **비밀번호:** **강력한 비밀번호** 입력. `password123` 등 쉬운 비밀번호는 사용하지 마세요. 실제 환경에서는 비밀번호 생성기로 복잡한 값을 만들어 쓰세요.
   *   **비밀번호 확인:** 동일한 비밀번호 재입력
   
   ‘사용자에 대해 DB 생성’ 옵션에서 ‘사용자명과 동일한 DB 생성 및 모든 권한 부여’ 선택. 예를 들면 `contao_user` DB가 자동 생성되고, 해당 사용자에게 모든 권한이 부여됩니다.
   
   *   ‘모든 권한 부여’ 체크
   *   하단 ‘실행’ 버튼 클릭으로 사용자 및 DB 생성을 완료합니다.
   

4단계: ServBay에서 웹사이트 설정

방금 생성한 Contao 프로젝트 폴더를 대상으로 ServBay에서 웹사이트를 추가로 등록해야 합니다.

1. ServBay에서 새 웹사이트 추가

   ServBay 앱 메인 인터페이스를 엽니다. 왼쪽 메뉴에서 ‘웹사이트’ 탭 클릭 → ‘추가’ 버튼을 눌러 새 사이트를 등록합니다.

2. 웹사이트 정보 입력

   • 이름: 구분하기 쉬운 이름을 입력(예: My Contao Site)
   • 도메인: 로컬 개발용 도메인을 설정(권장: .local 또는 .servbay.demo 끝, 예: servbay-contao.local). ServBay에서 이 도메인을 자동으로 로컬 IP로 매핑합니다.
   • 웹사이트 타입: PHP 선택
   • PHP 버전: Contao 시스템 요구에 맞는 PHP 버전 선택(공식 문서 참고)
   • 웹사이트 루트 디렉터리: 매우 중요! Composer의 contao/managed-edition 설치 시, 웹 공개 파일(index.php 등)은 프로젝트 폴더 내 web 하위 폴더에 위치합니다. 즉, 루트 디렉터리에 /Applications/ServBay/www/servbay-contao-app/web을 입력해야 합니다.

3. 설정 저장

   모든 정보를 입력한 후, 하단의 ‘저장’ 버튼 클릭. ServBay가 새로운 사이트 설정을 적용합니다.

5단계: Contao 웹 설치 마법사 실행

웹사이트 등록 후, 브라우저에서 설정한 도메인에 접속하여 Contao 웹 설치 마법사를 진행할 수 있습니다.

1. 설치 페이지 접속

   브라우저를 열고, 지정한 도메인 뒤에 /contao/install을 붙여 접속(예: https://servbay-contao.local/contao/install)

   모든 설정이 올바르면 Contao 설치 화면이 보입니다.

2. 데이터베이스 정보 입력

   설치 마법사에서 데이터베이스 접속 정보를 입력합니다. 3단계에서 생성한 DB와 사용자 정보를 입력하세요:

   • DB 호스트: localhost
   • DB 이름: contao_user (phpMyAdmin에서 ‘사용자명과 동일한 DB 생성’ 선택 시)
   • 사용자명: contao_user
   • 비밀번호: 3단계에서 지정한 비밀번호

3. 관리자 정보 설정

   안내에 따라 Contao 백엔드 관리자 아이디, 비밀번호, 이메일 등 정보를 설정합니다. 반드시 강력한 비밀번호를 사용하세요.

4. 설치 완료

   남은 설치 절차(대개 DB 테이블 생성 등)는 가이드에 따라 버튼(‘설치’ 또는 ‘완료’ 등)을 눌러 마무리하세요.

6단계: 설치 확인 및 백엔드 로그인

설치 완료 후, Contao가 제대로 동작하는지 확인하고 관리 백엔드에 접속해보세요.

1. 사이트 프론트 접속

   브라우저에서 지정한 도메인(예: https://servbay-contao.local/) 접속 시, Contao 기본 환영 페이지 또는 빈 화면(Contao 기본 설정에 따라 다름)이 노출됩니다. 이는 웹서버가 정상 작동하고 Contao 프론트엔드에 접근 가능한 상태를 의미합니다.

2. Contao 백엔드 접속

   Contao 백엔드 로그인 페이지 접속: 일반적으로 https://servbay-contao.local/contao

   설치 5단계에서 생성한 관리자 계정 정보로 로그인하세요. 정상 로그인 시, Contao 관리 콘솔에 입장해 콘텐츠 생성, 확장 모듈 설치, 사이트 설정 등이 가능합니다.

자주 묻는 질문 (FAQ)

Q: https://servbay-contao.local/ 또는 https://servbay-contao.local/contao/install 접속 시 오류가 발생합니다. 어떻게 하나요?

A:

• ServBay 실행 여부 확인: ServBay 앱이 실행 중이며, PHP 및 웹서버(Caddy 또는 Nginx 등)가 정상 가동 중인지 확인
• ServBay 사이트 설정 재확인: 사이트 드라이버(도메인, 웹사이트 타입, PHP 버전, 웹사이트 루트 디렉토리)가 제대로 지정됐는지 다시 확인 특히, contao/managed-edition의 루트는 프로젝트 내 web 폴더임을 유의
• 도메인 네임 해석 확인: ServBay는 .local 도메인의 자동 매핑을 지원합니다. 다른 도메인 사용시에는 ServBay 재시작 혹은 시스템 hosts 파일 상태 확인(일반적으로 ServBay가 자동 관리)
• 웹서버 로그 확인: ServBay의 웹서버 로그(Caddy, Nginx 등)를 살펴보면 상세 오류 내용 확인 가능

Q: 데이터베이스 연결에 실패합니다. 해결방법이 있나요?

A:

• 데이터베이스 서비스 실행 확인: ServBay에서 MySQL/MariaDB 또는 PostgreSQL이 실행 중인지 확인
• DB 접속 정보 다시 입력: Contao 설치 마법사에서 작성한 DB 호스트(localhost), DB 이름, 사용자명, 비밀번호가 phpMyAdmin에서 생성한 값과 일치하는지 확인
• DB 사용자 권한 확인: 새로운 DB 사용자가 해당 DB에 모든 권한을 부여받았는지 점검

Q: 설치 중 권한 오류가 발생합니다.

A: Contao 설치 마법사는 특정 디렉토리에 쓰기 권한이 필요합니다. ServBay 기본 설정으로도 충분하지만 권한 관련 문제가 발생한다면, 터미널에서 Contao 프로젝트 폴더 권한을 아래처럼 조정할 수 있습니다:

cd /Applications/ServBay/www/servbay-contao-app
sudo chown -R your_username:staff . # your_username을 macOS 사용자명으로 변경
sudo chmod -R 755 .
sudo chmod -R 777 var/ cache/ system/config/ # Contao가 해당 디렉터리의 쓰기 권한을 필요로 함

chmod 777은 생산 서버에서는 보안상 권장되지 않지만, 로컬 개발 환경에서 권한 이슈 해결 목적으로는 일반적으로 사용됩니다.

마무리

이 가이드를 따라 ServBay 로컬 개발 환경에서 Contao CMS를 성공적으로 설치 및 설정하셨을 것입니다. ServBay의 통합 환경은 Composer 의존성 관리, DB 설정, 웹서버 구성까지의 과정을 대폭 단순화해 Contao 개발에 집중할 수 있게 도와줍니다. 이제 Contao 백엔드에서 콘텐츠 생성, 페이지 디자인, 확장 기능이나 테마 설치를 진행하며 자유롭게 웹사이트를 만들어보세요.

Contao의 심화 기능 및 사용법은 Contao 공식 문서를 참고하시기 바랍니다.