ServBay

한국어

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย

한국어

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Tiếng Việt
Türkçe
Italiano
हिन्दी
Bahasa Indonesia
Bahasa Melayu
Polski
Nederlands
Українська
ไทย

Appearance

ServBay 환경에서 Jigsaw 설치 및 구성 ​

개요 ​

이 문서는 강력한 로컬 웹 개발 환경인 ServBay에서 Jigsaw 정적 사이트 생성기를 설치하고 구성하는 방법을 안내합니다. ServBay는 PHP, Node.js 등 다양한 기술 스택의 통합 개발 환경을 제공하여 Jigsaw 프로젝트의 셋업 과정을 크게 단순화합니다. ServBay를 통해 Jigsaw 프로젝트에 로컬 도메인, HTTPS, 고성능 웹 서버를 손쉽게 설정할 수 있어 사이트 콘텐츠 개발에만 집중할 수 있습니다.

Jigsaw란 무엇인가요? ​

Jigsaw는 Tighten에서 개발한 Laravel 컴포넌트 기반의 정적 사이트 생성기입니다. Laravel Blade 템플릿 엔진의 강력함과 유연성을 활용하며, Markdown 파일을 조합해 순수 정적 HTML 사이트를 생성합니다. Jigsaw는 문서 사이트, 블로그, 마케팅 랜딩 페이지 등 데이터베이스와 동적 서버 처리가 필요 없는 웹사이트 제작에 매우 적합합니다. 주요 장점은 다음과 같습니다:

  • 익숙한 도구 활용: Laravel이나 Blade 템플릿에 익숙하다면 Jigsaw를 빠르게 배울 수 있습니다.
  • 성능과 보안: 생성된 정적 사이트는 로딩 속도가 빠르고, 서버 측 코드 실행이 없어 보안성이 높습니다.
  • 유연한 템플릿: Blade 템플릿을 사용해 복잡한 레이아웃과 컴포넌트를 만들 수 있습니다.
  • Markdown 지원: 쉽게 콘텐츠를 작성할 수 있습니다.

활용 사례 ​

Jigsaw는 아래와 같은 경우에 적합합니다:

  • 프로젝트 문서 및 API 문서 사이트
  • 개인 블로그/기술 공유 웹사이트
  • 기업/제품의 마케팅 랜딩 페이지
  • 소규모 포트폴리오 및 홍보 사이트
  • 높은 성능과 보안, 고정된 콘텐츠가 필요한 웹사이트

사전 준비 사항 ​

시작 전에 아래 조건을 충족하는지 확인하세요:

  1. ServBay 설치 및 실행: macOS에 ServBay를 설치하고 실행하세요. ServBay에는 PHP, Composer, Node.js/npm이 내장되어 있어 Jigsaw를 설치하고 실행하는 데 필요합니다.
  2. 기본 명령어 사용법 숙지: 터미널에서 명령어를 사용할 줄 알아야 합니다.
  3. Composer 및 npm 기초 지식: Jigsaw 설치에는 Composer가, 프론트엔드 자산 컴파일에는 npm이 필요합니다.

설치 및 구성 단계 ​

아래는 ServBay 환경에서 Jigsaw 프로젝트를 설치하고 구성하는 단계별 안내입니다.

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

먼저 터미널을 열고, ServBay에서 권장하는 웹사이트 루트 디렉토리인 /Applications/ServBay/www로 이동한 뒤 Jigsaw 프로젝트용 서브디렉토리를 생성합니다.

bash
cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

프로젝트 디렉토리명을 servbay-jigsaw-demo로 지정하며, 모든 프로젝트 파일이 여기에 위치하게 됩니다.

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

ServBay는 이미 Composer가 설치되어 있어 터미널 어디서나 composer 명령을 사용할 수 있습니다. 방금 생성한 프로젝트 디렉토리(/Applications/ServBay/www/servbay-jigsaw-demo)에서 아래 명령어를 실행해 Jigsaw 프로젝트를 만듭니다:

bash
composer create-project tightenco/jigsaw .

이 명령어는 최신 버전의 Jigsaw와 모든 PHP 의존성을 현재 디렉토리(.)에 설치합니다. 마지막의 .은 프로젝트를 현재 디렉토리에 생성한다는 의미로, 별도의 jigsaw 서브디렉토리를 만들지 않습니다.

3단계: ServBay 사이트 구성 ​

웹 브라우저로 Jigsaw 사이트를 열기 위해, ServBay에서 해당 프로젝트에 대해 새 로컬 웹사이트를 설정해야 합니다.

  1. ServBay UI 실행: ServBay 앱 아이콘을 더블 클릭하거나 메뉴바 아이콘을 통해 ServBay 컨트롤 패널을 엽니다.
  2. "사이트"로 이동: 왼쪽 네비게이션 바에서 "사이트" 탭을 클릭합니다.
  3. 새 사이트 추가: 하단의 "+" 버튼을 클릭해 "사이트 추가"를 선택합니다.
  4. 사이트 상세 정보 설정:
    • 이름 (Name): 예를 들어 ServBay Jigsaw Demo와 같이 식별하기 쉬운 이름을 입력합니다.
    • 도메인 (Domain): 로컬 접속에 사용할 도메인을 입력합니다. .servbay.demo로 끝나는 도메인을 사용하면 실제 도메인과 충돌을 피할 수 있습니다. 예: jigsaw-demo.servbay.demo. ServBay가 .servbay.demo 도메인을 자동으로 로컬로 매핑합니다.
    • 사이트 종류 (Site Type): Jigsaw 빌드 과정에 PHP가 필요하므로 PHP를 선택합니다.
    • PHP 버전 (PHP Version): ServBay에 설치된 버전 중 최신 안정 버전을 선택하는 것을 권장합니다.
    • 사이트 루트 (Site Root): 매우 중요한 단계입니다. Jigsaw가 빌드한 정적 파일은 기본적으로 프로젝트 루트의 build_local 폴더에 생성됩니다. 따라서 사이트 루트를 아래와 같이 지정해야 합니다: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
  5. 저장 및 적용: 정보를 모두 입력했다면 "저장"을 클릭하세요. 변경 적용을 묻는 안내가 나오면 확인을 눌러줍니다. ServBay가 자동으로 (Caddy 또는 Nginx) 웹 서버 설정을 업데이트하고, HTTPS도 함께 적용됩니다.

4단계: 프런트엔드 의존성 설치 ​

Jigsaw 프로젝트에서는 종종 SASS 및 JavaScript 파일 등 프런트엔드 자산을 관리하고 빌드하기 위해 npm을 사용합니다. ServBay 환경에는 Node.js와 npm이 함께 제공됩니다.

프로젝트 디렉토리(/Applications/ServBay/www/servbay-jigsaw-demo)에서 다음 명령어로 프런트엔드 의존성을 설치하세요:

bash
npm install

프로젝트 루트의 package.json을 읽어서 필요한 Node.js 모듈들을 node_modules 디렉토리에 설치합니다.

5단계: Jigsaw 사이트 빌드 ​

의존성 설치가 모두 끝나면, Jigsaw 빌드 명령어를 실행하여 정적 사이트 파일을 생성해야 합니다.

아래 명령을 프로젝트 디렉토리에서 실행하세요:

bash
./vendor/bin/jigsaw build

이 명령어의 동작:

  1. source 폴더의 Markdown 파일과 Blade 템플릿을 처리
  2. webpack.mix.js에서 정의한 빌드 작업 수행(프로젝트에 Laravel Mix가 적용된 경우)
  3. 최종 정적 HTML, CSS, JS, 기타 자산을 build_local 디렉토리로 출력

6단계: 웹사이트 접속 확인 ​

이제 /Applications/ServBay/www/servbay-jigsaw-demo/build_local 디렉토리에 Jigsaw 사이트의 정적 파일이 생성되었습니다. 앞서 ServBay에서 사이트 루트를 이 디렉토리로 설정했기 때문에, 브라우저에서 입력한 도메인으로 사이트를 볼 수 있습니다.

웹 브라우저를 열고 3단계에서 지정한 도메인(예: https://jigsaw-demo.servbay.demo)에 접속하세요. ServBay는 사용자 전용 CA로 자동으로 HTTPS 인증서를 발급하므로 Jigsaw의 기본 환영 페이지를 볼 수 있습니다.

커스터마이징 및 개발 ​

이제 기본 환경 구축이 완료되었으므로, 자유롭게 Jigsaw 사이트의 콘텐츠와 스타일을 수정할 수 있습니다.

콘텐츠 및 템플릿 편집 ​

  • 사이트 소스 코드는 프로젝트 루트의 source 폴더에 위치합니다.
  • HTML 레이아웃 및 컴포넌트는 Blade 템플릿(source/_layouts, source/_partials 등)에 정의되어 있습니다.
  • 페이지 콘텐츠는 주로 Markdown 문서로 작성되며 source 또는 그 하위 디렉토리(예: source/index.md, source/about.md)에 저장됩니다.
  • 블로그 글은 보통 source/_posts 폴더에 YYYY-MM-DD-slug.md 형식으로 생성합니다.

새 페이지/글 추가 ​

새 페이지나 블로그 글을 추가하려면 source 디렉토리나 해당 하위 폴더(예: source/_posts)에 새로운 Markdown 파일만 생성하면 됩니다.

예를 들어, source/about.md 파일을 아래와 같이 만듭니다:

markdown
---
title: "회사 소개"
description: "ServBay Jigsaw Demo에 대한 자세한 정보"
---

# 회사 소개

이 페이지는 Jigsaw로 만든 About 페이지입니다.

여기에 회사 소개, 팀 정보 등 원하는 내용을 추가하실 수 있습니다.

스타일 및 스크립트 커스터마이징 ​

Jigsaw 프로젝트는 Laravel Mix(webpack.mix.js)를 이용해 프런트엔드 자산을 빌드하는 경우가 많습니다.

  • 스타일 파일(SASS/SCSS)은 source/_assets/sass 폴더에,
  • JavaScript 파일은 source/_assets/js 폴더에 위치합니다.

npm 스크립트를 통해 다음과 같이 자산을 빌드할 수 있습니다:

  • npm run dev: 개발용 빌드(소스 맵 포함, 비압축)
  • npm run watch: 개발용 빌드를 실시간 감시하며 자동 재빌드(개발 중 유용)
  • npm run prod: 운영 환경용 빌드(최적화 압축)

예를 들어, source/_assets/sass/main.scss를 수정한 후 npm run dev 또는 npm run watch로 CSS 파일을 빌드할 수 있습니다.

사이트 재빌드 ​

중요: source 하위의 콘텐츠 파일(Markdown) 또는 **템플릿 파일(Blade)**을 수정한 후에는 Jigsaw 빌드 명령을 다시 실행해야만 변경 사항이 build_local에 반영됩니다:

bash
./vendor/bin/jigsaw build

**프런트엔드 자산(SASS, JS)**을 수정했다면 npm run dev 또는 npm run watch로 재컴파일해야 합니다. 대부분의 Jigsaw 프로젝트에서는 build 명령 시 Mix 빌드도 자동 실행되지만, 별도로 빌드해두면 디버깅에 도움이 됩니다.

유의 사항 ​

  • 빌드 출력 디렉토리: Jigsaw 기본 빌드 출력은 build_local(개발용), build_production(운영용)입니다. ServBay 사이트 루트가 원하는 폴더(build_local)로 정확히 지정되어 있는지 확인하세요.
  • 웹 서버: ServBay는 Caddy 또는 Nginx를 웹 서버로 사용하며, 이들은 build_local의 정적 파일을 직접 서비스하므로 매우 효율적입니다. Jigsaw의 내장 jigsaw serve는 빠른 미리보기용이며, ServBay의 정식 웹 서버만큼 강력하지 않습니다.
  • HTTPS: ServBay는 .servbay.demo 도메인에 대해 자동으로 HTTPS를 설정하고 ServBay User CA를 사용해 인증서를 발급합니다. 브라우저 경고 없이 사용하려면 ServBay User CA 인증서를 시스템에 신뢰 기관으로 설치해야 할 수 있습니다.
  • 클린 빌드: 빌드 관련 문제 발생 시, 아래 명령어로 클린 빌드를 시도해보세요. ./vendor/bin/jigsaw build --clean

자주 묻는 질문 (FAQ) ​

Q: Markdown 파일을 수정했는데 브라우저에 바로 적용되지 않습니다.

A: 콘텐츠나 템플릿을 수정한 뒤에는 터미널에서 ./vendor/bin/jigsaw build 명령을 실행하여 사이트를 재빌드해야 합니다.

Q: SCSS 파일을 수정했는데 스타일이 바로 적용되지 않습니다.

A: 프런트엔드 자산을 수정한 경우, 프로젝트 폴더에서 npm run dev 또는 npm run watch로 다시 빌드해야 합니다.

Q: 로컬 도메인 접속 시 “접근 불가” 또는 “파일을 찾을 수 없음” 메시지가 나옵니다.

A: 아래 항목을 확인하세요:

  1. ServBay가 정상적으로 실행 중인지 확인
  2. ServBay의 해당 사이트 설정에서 도메인 및 사이트 루트가 올바르게 지정되었는지 확인 (/Applications/ServBay/www/servbay-jigsaw-demo/build_local)
  3. ./vendor/bin/jigsaw build 명령 실행 후 build_local 디렉토리 내에 index.html과 같은 정적 파일이 실제로 생성되어 있는지 확인

Q: Jigsaw 사이트를 운영 서버에 배포하려면 어떻게 해야 하나요?

A: Jigsaw는 완전 정적 파일만 생성합니다. 일반적인 배포 과정은 아래와 같습니다:

  1. ./vendor/bin/jigsaw build production 명령으로 운영용 최적화 빌드
  2. build_production 폴더의 모든 파일을 Netlify, Vercel, GitHub Pages, 각종 클라우드 스토리지 등 정적 사이트 호스팅 서비스에 업로드

요약 ​

ServBay를 활용하면 macOS 환경에서 Jigsaw 정적 사이트 생성기의 설치 및 구성이 매우 쉽고 빠릅니다. ServBay는 PHP, Composer, Node.js, npm 등 필수 런타임 일체와 강력한 로컬 웹 서버, 손쉬운 사이트 관리 기능을 제공합니다. 본 가이드의 단계를 따라하면 Jigsaw 프로젝트를 신속하게 시작할 수 있으며, ServBay의 다양한 기능으로 로컬 개발 생산성을 극대화할 수 있습니다.