ServBay 환경에서 OctoberCMS 설치 및 설정하기

개요

OctoberCMS는 강력한 Laravel 프레임워크를 기반으로 한 오픈 소스 콘텐츠 관리 시스템(CMS)으로, 간결함, 유연성, 개발자 친화성 덕분에 많은 사랑을 받고 있습니다. 이 문서에서는 macOS에 특화된 올인원 로컬 웹 개발 환경인 ServBay에서 OctoberCMS를 성공적으로 설치 및 설정하는 방법을 안내합니다. 이를 통해 OctoberCMS 기반 프로젝트 개발을 빠르게 시작할 수 있습니다.

OctoberCMS란?

OctoberCMS는 직관적인 백엔드 UI와 강력한 프런트엔드 개발 기능을 제공합니다. 개발자는 익숙한 Laravel 개념(예: Eloquent ORM, Blade 템플릿 엔진 등)을 활용해 간단한 블로그부터 복잡한 엔터프라이즈 애플리케이션까지 다양한 웹사이트를 구축할 수 있습니다.

사전 준비 사항

OctoberCMS를 설치하기 전에 다음 조건을 충족하는지 확인하세요.

macOS 시스템에 ServBay가 설치 및 실행 중이어야 합니다.
ServBay에서 PHP(권장 7.4 이상)와 MySQL/MariaDB 패키지를 활성화 및 실행해야 합니다.
ServBay의 Composer 패키지가 활성화되어 있어야 합니다.
기본적인 커맨드라인 사용법을 알고 있어야 합니다.

OctoberCMS 설치 단계

아래는 ServBay 환경에서 OctoberCMS를 설치·설정하는 상세 단계입니다.

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

먼저, ServBay의 권장 웹사이트 루트 디렉터리인 /Applications/ServBay/www로 이동 후, OctoberCMS 프로젝트용 새 폴더를 생성합니다.

bash

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

2단계: Composer로 OctoberCMS 설치

ServBay는 Composer가 기본 포함 및 설정되어 있습니다. ServBay 제어판에서 Composer 패키지가 활성화되었는지 확인하세요. 이제, 방금 생성한 프로젝트 폴더에서 아래 명령어로 OctoberCMS 핵심 파일을 다운로드·설치합니다.

bash

composer create-project october/october .

이 명령어는 OctoberCMS 공식 저장소에서 최신 버전을 현재 디렉터리(.)에 다운로드합니다.

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

OctoberCMS는 콘텐츠, 사용자, 설정 등 정보를 저장할 데이터베이스가 필요합니다. ServBay에 내장된 phpMyAdmin 도구를 사용해 데이터베이스와 사용자를 생성하겠습니다.

phpMyAdmin 데이터베이스 관리 도구 접속
브라우저를 열고 ServBay 로컬 개발 패널 https://servbay.host/에 접속합니다. ServBay가 제공하는 phpMyAdmin 링크(일반적으로 https://servbay.host/phpmyadmin/)로 이동하여 phpMyAdmin을 엽니다.
데이터베이스 사용자 생성
보안 및 서비스 분리를 위해, 앱마다 독립적인 데이터베이스 사용자 및 데이터베이스를 생성하는 것이 좋습니다.
1. 사용자 계정 페이지 이동
  phpMyAdmin 메인화면 상단 메뉴에서 “사용자 계정”을 클릭합니다.
2. 새 사용자 추가
  “사용자 계정 추가”를 클릭 후 아래 정보를 입력하세요.
  - 사용자명: OctoberCMS에서 사용할 사용자명(예: october_user)
  - 호스트명: localhost 또는 127.0.0.1 선택 — 해당 사용자는 로컬에서만 DB에 접속 가능함(보안 강화)
  - 비밀번호: 안전하고 고유한 비밀번호 입력(예시 비밀번호 password123은 실제 운영 환경에서 절대 사용하지 마세요)
  - 비밀번호 재입력: 위에서 입력한 비밀번호와 동일하게 입력
  - “데이터베이스 사용자에게 생성” 항목에서 “사용자명과 동일한 데이터베이스를 생성하며, 모든 권한 부여” 선택 — 이렇게 하면 october_user라는 이름의 데이터베이스가 자동 생성되며, 해당 사용자에게 모든 권한이 부여됩니다.
  - “글로벌 권한”에서 “모든 권한 부여”가 체크되어 있는지 확인(이전 항목에서 이미 체크했다면 추가 조치 없이 진행 가능)
  - 페이지 하단 “실행” 버튼을 클릭하여 사용자 및 DB 생성을 완료합니다.

4단계: 웹 서버 설정(ServBay 사이트 추가)

브라우저에서 OctoberCMS 앱에 접근하려면 ServBay에서 로컬 사이트 구성을 해야 합니다.

신규 사이트 추가
ServBay 제어판을 열고 왼쪽 메뉴의 “사이트(구버전에는 ‘호스트’로 표시될 수 있음)” 탭을 클릭합니다. “사이트 추가” 버튼을 누르세요.
다음 정보를 입력합니다.
- 이름: 식별하기 쉬운 사이트 이름(예: My OctoberCMS Site)
- 도메인: 로컬에서 사용할 도메인(예: servbay-octobercms.local) — .local 도메인 사용을 권장(실제 도메인과 충돌 방지)
- 사이트 유형: PHP 선택
- PHP 버전: 사용하고 싶은 PHP 버전 선택(ServBay에서 활성화한 버전과 동일 및 OctoberCMS 요구 사항 충족 필요)
- 사이트 루트 디렉터리: 탐색기 버튼을 눌러 1단계에서 생성한 프로젝트 폴더 /Applications/ServBay/www/servbay-octobercms-app 선택
설정 저장 및 ServBay 재시작
입력 후 저장 버튼을 클릭하면 ServBay가 변경사항 반영을 요청합니다. 관련 패키지(Caddy, Nginx 등) 및 ServBay 자체 재시작 작업이 필요할 수 있으니, 안내에 따라 진행하세요. ServBay는 자동으로 servbay-octobercms.local 도메인을 로컬(127.0.0.1)로 매핑합니다.

5단계: OctoberCMS 환경 변수 파일 설정

OctoberCMS(및 Laravel)는 .env 파일로 환경변수(데이터베이스 연결, 앱 키 등)를 관리합니다.

환경설정 파일 예시 복사
OctoberCMS 프로젝트 루트(/Applications/ServBay/www/servbay-octobercms-app)에서 .env.example 파일을 .env로 복사합니다.
bash
```
cd /Applications/ServBay/www/servbay-octobercms-app
cp .env.example .env
```
1
2

.env 파일 편집

선호하는 텍스트 에디터로 .env 파일을 엽니다. 데이터베이스 관련 항목을 3단계에서 만든 값으로 수정하세요.

ini

# ... 다른 설정 ...

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=october_user  # 생성한 데이터베이스 이름으로 교체
DB_USERNAME=october_user  # 생성한 사용자 이름으로 교체
DB_PASSWORD=password123   # 설정한 비밀번호로 교체

# ... 다른 설정 ...

중요: DB_DATABASE, DB_USERNAME, DB_PASSWORD 값은 실제로 생성한 정보로 반드시 변경해야 합니다.

6단계: OctoberCMS 설치 마법사 실행

OctoberCMS는 웹 기반 설치 마법사를 통해 마지막 설정(데이터베이스 마이그레이션, 관리자 계정 생성 등)을 진행합니다.

설치 페이지 접속
브라우저를 열고, 4단계에서 추가한 로컬 도메인 뒤에 /install.php를 붙여 접속하세요.
https://servbay-octobercms.local/install.php
OctoberCMS 설치 마법사 화면이 나타납니다.
데이터베이스 정보 입력
설치 마법사에서 데이터베이스 연결 정보를 요구할 때, .env 파일과 동일한 값을 차례로 입력하세요.
- 데이터베이스 타입: MySQL
- 데이터베이스 호스트: localhost 또는 127.0.0.1
- 데이터베이스 명: october_user
- 데이터베이스 사용자명: october_user
- 데이터베이스 비밀번호: password123
(다시 한 번, 실제 설정한 비밀번호를 입력하세요.)
관리자 계정 정보 입력
안내에 따라 OctoberCMS 관리자 로그인에 사용할 계정의 사용자명·비밀번호·이메일 등을 입력합니다.
설치 완료
“설치” 또는 그와 유사한 버튼을 클릭하세요. 데이터베이스 마이그레이션, 앱 시크릿키 생성 등 설치 작업이 수행됩니다. 완료까지 잠시 기다립니다.

7단계: 플러그인 및 테마 설치(선택 사항)

설치가 끝나면, OctoberCMS 관리자 백오피스(https://servbay-octobercms.local/backend)에 로그인할 수 있습니다.

플러그인 설치
백오피스에서 “시스템” → “업데이트” → “플러그인”으로 이동 후, 다양한 플러그인을 검색 및 설치해 기능을 확장할 수 있습니다.
테마 설치
“시스템” → “업데이트” → “테마” 메뉴로 이동해 프로젝트에 맞는 테마를 둘러보고 설치할 수 있습니다.

설치 후 기본 설정 및 사용

OctoberCMS 설치가 완료되면, 이제 본격적으로 사이트를 구축할 수 있습니다. 다음은 자주 사용하는 초기 작업 예시입니다.

프런트엔드 접속: https://servbay-octobercms.local/에서 사이트 메인 페이지(기본 테마)를 볼 수 있습니다.
백오피스 접속: https://servbay-octobercms.local/backend에서 설치한 관리자 계정으로 로그인합니다.
페이지 생성: 백오피스 → “CMS” → “페이지”에서 사이트 페이지를 생성·편집합니다.
콘텐츠 블록 생성: 백오피스 → “CMS” → “콘텐츠”에서 재사용 가능한 콘텐츠 조각을 만듭니다.
테마 설정: “CMS” → “테마”에서 현재 테마의 레이아웃, 파셜, 설정 등을 조정할 수 있습니다.
사용자 및 권한 관리: “시스템” → “관리”에서 백오피스 사용자와 권한을 관리합니다.

자주 묻는 질문(FAQ)

Q: servbay-octobercms.local 접속 시 ServBay 기본 화면 또는 오류가 출력됩니다.
- A: ServBay 제어판에서 servbay-octobercms.local 사이트가 정상 추가되었고, 루트 디렉터리가 /Applications/ServBay/www/servbay-octobercms-app으로 정확히 지정되어 있는지 확인하세요. 사이트 구성 후 ServBay를 반드시 재시작해야 반영됩니다. 또한 Caddy/Nginx, PHP 패키지가 정상 실행 중인지 확인하세요.
Q: https://servbay-octobercms.local/install.php 접속 시 빈 화면 또는 에러가 출력됩니다.
- A: 주로 PHP 오류입니다. ServBay 제어판의 PHP 에러 로그에서 원인을 확인하세요. 권한(서버 사용자에게 storage, themes, plugins 디렉터리 및 하위 폴더의 쓰기 권한 부여), PHP 버전·확장자 누락 등 다양한 원인이 있을 수 있습니다.
Q: 설치 도중 데이터베이스 연결 오류가 발생합니다.
- A: .env 파일의 DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD 값이 phpMyAdmin에서 실제 생성한 값과 완전히 일치하는지 확인하세요. ServBay의 MySQL/MariaDB가 실행 중인지도 확인합니다.
Q: composer create-project 명령 실행이 실패합니다.
- A: ServBay 제어판에서 Composer와 PHP 패키지가 활성화되어 있고, PHP 버전도 적절한지 확인하세요. 그리고, 네트워크 연결 상태를 확인하세요(Composer는 다운로드가 필요합니다).

마치며

ServBay가 제공하는 편리한 개발 환경을 활용하면, macOS에서 OctoberCMS를 쉽고 빠르게 설치 및 설정할 수 있습니다. 본 가이드의 단계를 따라하면, 다음 웹 프로젝트를 위한 강력하면서도 개발자 친화적인 로컬 개발환경을 완벽히 갖출 수 있습니다. 이제 OctoberCMS의 풍부한 기능을 경험하고, 멋진 사이트를 자유롭게 만들어보세요!

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

개요 ​

OctoberCMS란? ​

사전 준비 사항 ​

OctoberCMS 설치 단계 ​

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

2단계: Composer로 OctoberCMS 설치 ​

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

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

5단계: OctoberCMS 환경 변수 파일 설정 ​

6단계: OctoberCMS 설치 마법사 실행 ​

7단계: 플러그인 및 테마 설치(선택 사항) ​

설치 후 기본 설정 및 사용 ​

자주 묻는 질문(FAQ) ​

마치며 ​