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

개요

Sculpin은 PHP 기반의 강력하고 유연한 정적 사이트 생성기로, 블로그, 문서 사이트 또는 Twig 템플릿과 Markdown 파일 같은 동적 콘텐츠를 고성능 정적 HTML 페이지로 변환해야 하는 프로젝트에 특히 적합합니다. Composer로 의존성 관리를 하며, Symfony 컴포넌트를 활용해 개발자에게 친숙하고 신뢰할 수 있는 개발 경험을 제공합니다.

ServBay는 macOS에 특화된 로컬 웹 개발 환경으로, PHP, Composer, 데이터베이스(MySQL, PostgreSQL, MongoDB, Redis), 웹 서버(Caddy, Nginx) 등 다양한 필수 패키지를 통합하여 편리한 GUI 관리 도구를 제공합니다. ServBay를 활용하면 macOS에서 Sculpin 개발 환경을 구축할 때, PHP 버전 관리, 의존성 설치, 웹 서버 설정 등이 크게 단순해집니다.

이 가이드에서는 ServBay 환경에서 Sculpin을 설치 및 설정하고, 로컬 개발 웹사이트를 구축하는 과정을 단계별로 설명합니다.

적용 사례

• PHP 스택으로 고성능 정적 블로그를 구축하고자 할 때
• 오픈소스 프로젝트 또는 제품용 정적 문서 사이트 생성 시
• 데이터베이스 백엔드 없이 빠르게 정적 랜딩 페이지나 기업 웹사이트를 만들 때
• Twig 템플릿 엔진과 Markdown을 활용해 콘텐츠를 작성하며 정적 사이트의 속도와 보안을 누리고자 할 때

사전 준비 사항

시작 전 다음 조건을 충족해 주세요:

1. macOS에 ServBay가 설치되어 실행 중이어야 합니다. ServBay는 필수 PHP 환경, Composer, 웹 서버(Caddy 또는 Nginx)를 제공합니다.
2. 기본적인 터미널(명령행) 사용법을 숙지하고 있어야 합니다.
3. PHP, Composer, Markdown 기본 개념을 알고 있어야 합니다.

Sculpin 설치 단계

다음은 ServBay 환경에서 Sculpin을 설치 및 설정하는 상세 절차입니다.

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

먼저 ServBay 웹사이트 루트 디렉터리(/Applications/ServBay/www) 하위에 새로운 프로젝트 폴더를 만듭니다. 예시로 servbay-sculpin-app을 프로젝트명으로 사용하겠습니다.

터미널을 열고 아래 명령어를 실행하세요:

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

이 폴더가 Sculpin 프로젝트 파일을 보관할 위치입니다.

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

ServBay에는 Composer가 기본 내장되어 있어 별도의 설치가 필요 없습니다. 터미널에서 바로 composer 명령어를 사용할 수 있습니다.

Sculpin 공식 블로그 스켈레톤을 기반으로 빠르게 프로젝트를 시작할 수 있습니다. 앞서 만든 디렉터리 servbay-sculpin-app에서 다음 명령어를 실행하세요:

composer create-project sculpin/sculpin-blog-skeleton .

이 명령어는 Composer를 통해 Sculpin 블로그 스켈레톤과 모든 의존 패키지를 현재 폴더(.)에 내려받아 설치합니다.

3단계: ServBay 사이트 설정

Sculpin 사이트를 ServBay의 웹 서버(Caddy 또는 Nginx)로 서빙하기 위해 ServBay에서 사이트를 추가해야 합니다.

1. ServBay 앱 실행: ServBay GUI를 실행합니다.
2. ‘사이트’ 탭 이동: ServBay 창 상단 내비게이션의 ‘사이트’ 탭을 클릭합니다.
3. 새 사이트 추가: 좌측 하단 ‘+’ 버튼을 클릭해 새로운 사이트를 추가합니다.
4. 사이트 정보 입력:
   • 이름(Name): 구분하기 쉬운 이름을 입력(예: My Sculpin Site)
   • 도메인(Domain): 로컬에서 사용할 도메인(예: servbay-sculpin.local). ServBay는 .local 도메인을 위한 로컬 해석 및 SSL 인증서를 자동으로 설정합니다(ServBay User CA 사용).
   • 사이트 유형(Type): PHP 선택(Sculpin은 PHP 앱이기 때문입니다)
   • PHP 버전(PHP Version): 원하는 PHP 버전을 선택합니다. ServBay는 다중 PHP 버전 지원, Sculpin과 호환 가능한 버전 중 최신권장.
   • 문서 루트(Document Root): 중요 단계입니다. Sculpin은 정적 파일을 기본적으로 output_dev 또는 output_prod 디렉터리에 생성합니다. 개발에서는 출력 디렉터리를 다음과 같이 지정합니다: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. 설정 저장: 모든 정보를 입력한 뒤 ‘저장’ 버튼 클릭. ServBay가 새 구성을 웹 서버(Caddy 또는 Nginx)에 자동 적용합니다. 보통 ServBay 서비스를 수동으로 재시작할 필요는 없습니다.

4단계: Sculpin 웹사이트 빌드

ServBay에 사이트가 추가된 후, Sculpin을 실행해 정적 파일을 생성해야 합니다.

터미널에서 현재 프로젝트의 루트 /Applications/ServBay/www/servbay-sculpin-app에 있는지 확인 후, 아래 명령어로 의존성을 설치하세요(2단계에서 이미 설치했다면 생략 가능하지만 한 번 더 실행해도 무방합니다):

composer install

그 다음, Sculpin 빌드 명령을 실행해 사이트를 생성합니다.

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Composer로 설치된 Sculpin 실행 파일 경로입니다.
• generate: Sculpin이 정적 사이트를 생성하는 명령어입니다. source 폴더의 내용과 템플릿을 읽어 기본적으로 output_dev에 결과를 생성합니다.
• --watch: source 폴더 내 파일 변경을 감지해 자동으로 사이트를 재생성합니다. 개발에 매우 편리한 옵션입니다.

명령 실행 후 "Sculpin has generated your site!"와 비슷한 결과 메시지가 나타나면, 정적 파일이 output_dev에 정상적으로 생성된 것입니다.

5단계: 로컬 개발 웹사이트 접속

이제 ServBay에 설정한 도메인으로 Sculpin 사이트에 접근할 수 있습니다.

웹 브라우저를 열고 3단계에서 지정한 도메인을 입력하세요:

https://servbay-sculpin.local

사이트의 루트 디렉터리를 output_dev로 지정하고, sculpin generate --watch가 실행 중이므로, 어떤 변경이든 https://servbay-sculpin.local에서 바로 실시간으로 살펴볼 수 있습니다. ServBay의 자동 SSL 인증서로 HTTPS 환경도 바로 경험할 수 있습니다.

Sculpin 활용한 개발 시작하기

이제 ServBay 환경에서 Sculpin 설치 및 구성을 마쳤으니, 본격적으로 정적 사이트를 개발할 수 있습니다. 다음은 기본 개발 과정입니다.

Sculpin 프로젝트 구조 개요

Sculpin의 기본 프로젝트 구조를 이해하면 개발에 도움이 됩니다:

servbay-sculpin-app/
├── app/                # 앱 설정 및 캐시 저장소
├── output_dev/         # 개발환경용 정적 파일(ServBay 문서 루트는 여기로)
├── output_prod/        # 운영환경용 정적 파일
├── source/             # 소스 파일(마크다운 콘텐츠, Twig 템플릿, 정적 리소스 등)
│   ├── _layouts/       # Twig 레이아웃 파일
│   ├── _posts/         # 블로그 글 Markdown 파일
│   ├── assets/         # 에셋(CSS, JS, 이미지 등)
│   └── index.md        # 메인 페이지 Markdown 파일
├── vendor/             # Composer로 설치된 패키지
├── sculpin.yml         # Sculpin 메인 설정 파일
├── composer.json       # Composer 의존성 설정
└── ...기타 파일

주요 작업은 source 디렉터리에서 이루어집니다.

블로그 포스트 작성

Sculpin 블로그에 새 포스트를 작성하려면 source/_posts 폴더에 마크다운 파일을 추가하면 됩니다. 파일명은 보통 YYYY-MM-DD-slug.md 패턴을 따릅니다.

예를 들어, 2024-06-06-my-first-post.md 파일을 만들 수 있습니다.

---
title: "나의 첫 번째 글"
date: 2024-06-06
tags: [튜토리얼, Sculpin, ServBay]
---

# 나의 첫 번째 글

이것은 Sculpin 블로그의 첫 글입니다. 이곳에 ServBay 및 Sculpin 사용 경험을 공유합니다.

Markdown 문법으로 누구나 쉽게 내용을 작성할 수 있습니다.

## 소제목

목록:
- 항목 1
- 항목 2

파일 작성 후, sculpin generate --watch가 작동 중이라면 파일 변경을 자동 감지해 사이트를 다시 빌드합니다. 브라우저에서 https://servbay-sculpin.local을 새로고침하면 새 글이 나타납니다.

새 페이지 만들기

독립적인 페이지(예: “회사 소개”)를 추가하려면 source 폴더에 마크다운 파일을 직접 만드세요. 예시: about.md

---
title: "회사 소개"
layout: page.html.twig # 사용할 레이아웃 파일 지정
---

# ServBay Sculpin 가이드 소개

이 페이지는 ServBay와 Sculpin으로 정적 웹사이트를 구축하는 방법을 안내합니다.

저장하면 Sculpin이 output_dev/about/index.html 파일을(‘pretty URL’ 설정 시) 자동 생성합니다. 이제 https://servbay-sculpin.local/about/에서 해당 페이지에 접근할 수 있습니다.

스타일 및 스크립트 커스터마이즈

CSS, JS와 같은 정적 리소스는 보통 source/assets 폴더에 위치합니다. 직접 파일을 수정하면 됩니다.

예를 들어, source/assets/css/style.css를 수정해 사이트 스타일을 바꿀 수 있습니다.

이 리소스들도 빌드시 출력 디렉터리에 복사되며, 파일 수정 시 Sculpin의 --watch 기능이 변경을 감지해 자동 재생성이 이루어집니다.

운영환경(생산)용 사이트 빌드

개발이 마무리되었으면, 배포용 생산 환경 버전을 빌드하세요. 이 과정에서 자원 파일 압축 등 추가 최적화가 진행됩니다.

운영환경 빌드에는 다음 명령을 사용합니다:

vendor/bin/sculpin generate --env=prod

이 명령으로 생성된 파일은 output_prod 폴더에 저장됩니다. 이 폴더 내 모든 파일을 Github Pages, Netlify, Vercel, 또는 본인 웹 서버 같은 정적 호스팅 서비스로 업로드하면 됩니다.

생산 빌드 결과물을 ServBay에서 직접 확인하고 싶다면, ServBay 사이트 설정의 ‘문서 루트’를 /Applications/ServBay/www/servbay-sculpin-app/output_prod로 변경 후 저장하면 지정 도메인에서 운영환경 결과물도 확인할 수 있습니다.

유의사항

• ServBay가 실행 중이며, 해당 사이트가 활성화 되어 있는지 확인하세요.
• sculpin generate --watch 명령이 터미널에서 정상적으로 돌아가는지 확인해 개발 중 자동 업데이트가 잘 되는지 점검하세요.
• ServBay 사이트 설정의 ‘문서 루트’가 output_dev(혹은 운영 시에는 output_prod)를 가리키고 있는지 확인해 주세요.
• ServBay는 .local 도메인에 SSL 인증서를 자동 제공하지만, 운영체제에 ‘ServBay User CA’ 신뢰 요구가 있을 수 있습니다. 자세한 방법은 ServBay 공식 문서를 참고하세요.

자주 묻는 질문 (FAQ)

Q: 파일을 수정했는데 웹사이트가 갱신되지 않아요.

A: 프로젝트 폴더에서 vendor/bin/sculpin generate --watch 명령이 실행 중인지 그리고 오류로 중단되지 않았는지 확인하세요. 터미널에 에러 메시지가 있는지도 점검하세요. 또한 브라우저 캐시를 비우거나 시크릿 모드로 접속해보세요.

Q: https://servbay-sculpin.local 접속 시 SSL 오류가 발생해요.

A: ServBay는 .local 도메인에 자체 서명한 SSL 인증서를 사용합니다. 운영체제에서 ‘ServBay User CA’를 신뢰해야 합니다. 자세한 방법은 ServBay 공식 문서의 안내를 따라 CA 인증서 설치 및 신뢰를 진행하세요.

Q: PHP 버전은 어떻게 변경할 수 있나요?

A: ServBay 앱의 ‘패키지’ 탭에서 다양한 PHP 버전을 설치하고 관리할 수 있습니다. 이후 ‘사이트’ 탭에서 Sculpin 사이트 설정을 수정해 원하는 PHP 버전을 선택 후 저장하면 됩니다.

Q: Sculpin이 지원하는 템플릿 언어나 마크업은 무엇인가요?

A: Sculpin은 기본적으로 Twig 템플릿 엔진을 사용하며, 콘텐츠 작성에 폭넓게 Markdown을 지원합니다.

요약

ServBay가 제공하는 통합 개발 환경 덕분에, macOS에서 Sculpin 정적 사이트 생성기를 쉽고 빠르게 설치 및 설정할 수 있습니다. 사전 구성된 PHP와 Composer, 그리고 간편한 웹 서버/SSL 관리 기능은 로컬에서 Sculpin 기반 프로젝트 개발을 신속하고 안정적으로 할 수 있게 해줍니다. 본 가이드에 따라 환경을 구축하고 Sculpin의 강력한 기능과 ServBay의 편리함을 결합하면, 복잡하고 번거로운 개발 환경 세팅에 시간을 빼앗기지 않고 고품질의 정적 웹사이트 제작에만 집중할 수 있습니다.