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

Kirby는 다양한 유형의 웹사이트 구축에 적합한 유연하고 강력한 파일 기반 콘텐츠 관리 시스템(CMS)입니다. 기존 데이터베이스 기반 CMS와 달리 Kirby는 콘텐츠를 파일 시스템에 저장하므로 매우 가볍고, 버전 관리에 유리하며 배포도 간편합니다.

이 튜토리얼에서는 개발자를 위해 설계된 현지 웹 개발 환경인 ServBay에서 Composer를 사용해 Kirby 4.2 Starterkit을 설치 및 설정하는 방법을 안내합니다. ServBay는 PHP, 웹 서버(Caddy 또는 Nginx), Composer가 미리 구성되어 있어 로컬에서 Kirby 개발을 위한 최적의 플랫폼입니다.

사전 준비 사항

시작 전에 아래가 준비되어 있어야 합니다.

ServBay가 macOS에 설치 및 실행 중이어야 합니다.
ServBay에서 필요한 PHP 버전이 활성화되어야 합니다(예시에서는 PHP 8.2 사용).
ServBay에는 Composer가 내장되어 있으므로 따로 설치할 필요가 없습니다.

Kirby 설치 단계

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

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

먼저 터미널을 엽니다. ServBay의 기본 웹사이트 루트 디렉토리인 /Applications/ServBay/www로 이동한 다음, 새로운 프로젝트 디렉토리를 만듭니다. 예시 프로젝트 이름으로 servbay-kirby-app을 사용하겠습니다.

bash

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

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

ServBay에는 Composer가 이미 통합되어 있어 터미널에서 바로 사용할 수 있습니다. 프로젝트 디렉토리(servbay-kirby-app)에서 다음 Composer 명령어를 실행해 Kirby Starterkit 프로젝트를 내려받아 생성합니다.

bash

composer create-project getkirby/starterkit .

위 명령은 Kirby의 핵심 파일, 의존성, 그리고 기본 콘텐츠와 템플릿이 포함된 Starterkit을 현재 디렉토리(.)에 다운로드합니다.

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

ServBay의 웹 서버(Caddy 또는 Nginx)가 Kirby 프로젝트를 서비스할 수 있도록 ServBay 애플리케이션에 새로운 웹사이트 구성을 추가해야 합니다.

ServBay 앱 열기: ServBay 앱을 실행합니다.
웹사이트 관리로 이동: ServBay 창 왼쪽 네비게이션에서 "웹사이트" 탭을 클릭합니다.
새 웹사이트 추가: 하단의 "+" 버튼 또는 웹사이트 추가 옵션을 클릭합니다.
웹사이트 정보 입력: 팝업되는 설정 창에 아래 정보를 입력하세요.
- 이름: 프로젝트를 쉽게 구분할 수 있는 이름(예: My Kirby Site)
- 도메인: 로컬 개발용 도메인을 지정합니다. .local 또는 .servbay.demo와 같은 접미사를 권장합니다(예: servbay-kirby.local). ServBay가 자동으로 로컬 DNS를 설정합니다.
- 사이트 유형: Kirby는 PHP 앱이므로 PHP를 선택합니다.
- PHP 버전: 사용할 PHP 버전 선택(예: 8.2). 이 버전이 Kirby의 최소 요구 사항을 충족하는지 확인하세요.
- 웹사이트 루트 디렉토리: Kirby 프로젝트에서 index.php가 위치한 디렉토리를 지정합니다. Starterkit의 경우, 프로젝트 루트 디렉토리가 해당됩니다. 1단계에서 생성한 경로인 /Applications/ServBay/www/servbay-kirby-app을 입력하거나 파일 선택기로 지정하세요.
설정 저장: 정보를 확인한 후 저장 버튼을 눌러 설정을 완료합니다. ServBay가 자동으로 새 구성을 적용하며, 웹 서버 재시작이 필요할 수 있습니다.

4단계: Kirby 설정(기본)

Kirby의 핵심 설정은 site/config/config.php 파일에서 관리합니다. Starterkit에서는 기본 설정이 완료되어 있어 바로 실행할 수 있습니다. 필요에 따라 이 파일에서 아래와 같은 맞춤 설정이 가능합니다.

debug 모드 활성화 (c::set('debug', true);)
패널 언어 설정
커스텀 라우팅 정의 등

프로젝트 루트에는 Starterkit이 자동으로 생성한 content 디렉토리가 있으며, 모든 페이지 콘텐츠가 저장됩니다.

5단계: Kirby 웹사이트 실행 및 접속

ServBay 설정이 완료되면 지정한 도메인을 통해 Kirby 웹사이트에 접속할 수 있습니다.

ServBay가 실행 중인지 확인: ServBay 앱이 실행 중이며, 관련 웹 서버(Caddy 또는 Nginx)와 PHP 패키지가 구동되고 있는지 확인하세요.
웹사이트 접속: 웹 브라우저를 열어 3단계에서 설정한 도메인(예: https://servbay-kirby.local)을 입력합니다.

Kirby Starterkit의 기본 환영 페이지가 표시되어야 합니다. ServBay는 기본적으로 HTTPS를 지원하므로, https://로 접속하는 것이 좋습니다.

6단계: Kirby 패널 설치 및 사용(선택사항)

Kirby는 사이트 콘텐츠, 사용자 및 설정을 쉽게 관리할 수 있는 강력한 관리 패널을 제공합니다.

패널 설치 페이지 접속: 브라우저에서 웹사이트 도메인 뒤에 /panel을 덧붙여 접속합니다(예: https://servbay-kirby.local/panel).
관리자 계정 생성: /panel에 처음 접속하면 패널 설치 화면이 나타납니다. 지시에 따라 사용자 이름, 비밀번호, 이메일 주소 등 필수 정보를 입력해 첫 번째 관리자 계정을 만드세요.
패널 로그인: 계정 생성 후 Kirby 패널에 로그인하여 시각적 인터페이스로 사이트 콘텐츠 관리를 시작할 수 있습니다.

Kirby로 사이트 구축하기

이제 ServBay 환경에 Kirby를 성공적으로 설치 및 설정했으니, Kirby의 파일 기반 특성을 활용하여 직접 사이트를 만들어 볼 수 있습니다. 아래는 Kirby 개발의 핵심 개념과 기본 사용법입니다.

콘텐츠 구조 (Content)

Kirby의 콘텐츠는 content 디렉터리에 저장됩니다. 각 페이지는 content 폴더 내에 별도의 하위 폴더로 존재합니다. 각 폴더 내에는 보통 page.txt와 같은 텍스트 파일에 Markdown 유사 문법으로 콘텐츠가 담깁니다.

예시: '회사소개' 페이지 생성하기

터미널에서:

bash

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: 회사소개\n----\n이곳은 회사소개 페이지 내용입니다." > content/about/about.txt

템플릿이 지원할 경우 https://servbay-kirby.local/about로 접속해 확인합니다.

템플릿 (Templates)

템플릿 파일은 site/templates 디렉토리에 있으며, 특정 페이지가 어떻게 그려질지 결정합니다. 파일명은 보통 콘텐츠 폴더명이나 블루프린트명과 일치합니다(예: about.php는 content/about 또는 about 블루프린트를 사용하는 페이지와 연결됩니다).

예시: about.php 템플릿 만들기

site/templates/about.php 파일에 다음과 같이 작성:

php

<?php snippet('header') ?>

<main>
  <h1><?= $page->title() ?></h1>
  <div class="text">
    <?= $page->text()->kt() // KirbyText로 렌더링 ?>
  </div>
</main>

<?php snippet('footer') ?>

여기서 snippet() 함수는 공통(header, footer 등) 재사용 부분을 불러올 때 사용됩니다.

블루프린트 (Blueprints)

블루프린트 파일은 site/blueprints 폴더에 위치하며, 패널에서 각 페이지의 구성, 필드, 옵션 등을 정의합니다. YAML 형식으로 작성됩니다.

예시: about.yml 블루프린트 만들기

site/blueprints/pages/about.yml에 다음 내용을 작성:

yaml

title: 소개 페이지

columns:
  - width: 2/3
    fields:
      text:
        label: 텍스트 콘텐츠
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # 사이드바 필드(예: 이미지 업로드 등)
      cover_image:
        label: 커버 이미지
        type: files
        max: 1
        uploads:
          template: image

블루프린트를 정의하면, 패널에서 새 ‘소개’ 페이지를 만들 때 위와 같은 필드 구성으로 입력할 수 있습니다.

스니펫 (Snippets)

스니펫은 PHP로 작성한 재사용 파일로, 보통 페이지의 헤더, 푸터, 내비게이션 등 반복되는 부분에 사용합니다. site/snippets 폴더에 저장합니다.

컨트롤러(Controllers) 및 모델(Models)

좀 더 복잡한 로직이 필요할 때는, site/controllers에서 컨트롤러를 통해 페이지 데이터를 처리하고, site/models에서 커스텀 페이지 클래스를 정의할 수 있습니다.

정적 리소스 (Assets)

CSS, JavaScript, 이미지 등 정적 리소스는 보통 프로젝트 루트의 assets 폴더에 보관합니다. 템플릿에서는 url('assets/...') 헬퍼 함수를 이용해 리소스 URL을 얻습니다.

예시: CSS 및 JS 파일 연결

site/templates/default.php나 site/snippets/header.php에서:

php

<link rel="stylesheet" href="<?= url('assets/css/style.css') ?>">
<script src="<?= url('assets/js/script.js') ?>"></script>

마무리

위 단계를 따라 ServBay 로컬 개발 환경에 Kirby CMS를 성공적으로 설치 및 설정하셨습니다. ServBay가 제공하는 통합 환경 덕분에 PHP 앱의 배포와 관리가 훨씬 쉬워졌으며, 이제 Kirby의 강력함과 파일 중심의 유연성을 십분 활용해 사이트를 개발할 수 있습니다. 앞으로 Kirby의 템플릿, 블루프린트, 스니펫 등 다양한 개념을 더 깊이 익혀 복잡한 웹사이트 구조와 기능도 직접 구현해보세요.

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

사전 준비 사항 ​

Kirby 설치 단계 ​

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

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

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

4단계: Kirby 설정(기본) ​

5단계: Kirby 웹사이트 실행 및 접속 ​

6단계: Kirby 패널 설치 및 사용(선택사항) ​

Kirby로 사이트 구축하기 ​

콘텐츠 구조 (Content) ​

템플릿 (Templates) ​

블루프린트 (Blueprints) ​

스니펫 (Snippets) ​

컨트롤러(Controllers) 및 모델(Models) ​

정적 리소스 (Assets) ​

마무리 ​

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

사전 준비 사항

Kirby 설치 단계

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

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

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

4단계: Kirby 설정(기본)

5단계: Kirby 웹사이트 실행 및 접속

6단계: Kirby 패널 설치 및 사용(선택사항)

Kirby로 사이트 구축하기

콘텐츠 구조 (Content)

템플릿 (Templates)

블루프린트 (Blueprints)

스니펫 (Snippets)

컨트롤러(Controllers) 및 모델(Models)

정적 리소스 (Assets)

마무리