ServBay 디렉터리 구조 완벽 해설

개요

ServBay는 macOS와 Windows를 지원하는 로컬 웹 개발 환경으로, 직관적이고 정돈된 디렉터리 구조를 제공합니다. Linux/Unix 시스템에 익숙하다면, ServBay의 파일 구조가 표준 파일 시스템과 유사해 빠르게 파일 위치를 파악하고 관리할 수 있습니다.

ServBay 설치 위치

ServBay 기본 설치 경로는 다음과 같습니다:

• macOS: /Applications/ServBay
• Windows: C:\ServBay

디렉터리 구조를 이해하면 로컬 개발, 환경 설정, 문제 해결, 데이터 백업에 효율성을 높일 수 있습니다. 본 문서에서는 ServBay 주요 디렉터리와 그 용도를 자세히 설명합니다.

ServBay의 대표적인 디렉터리 구조는 다음과 같습니다:

ServBay
|____backup                 # 백업 파일 디렉터리
| |____config               # 설정 파일 백업
| |____databases            # 데이터베이스 백업
| |____ssl                  # SSL 인증서 백업
| |____websites             # 웹사이트 파일 백업
|____bin                    # 사용자 실행 파일 디렉터리 (package/bin의 심볼릭 링크)
|____data                   # ServBay 내부 데이터 디렉터리
| |____servbay              # ServBay 핵심 설정 및 데이터
|____db                     # 데이터베이스 파일 저장 디렉터리
| |____mariadb              # MariaDB 데이터 파일
| |____mongodb              # MongoDB 데이터 파일
| |____mysql                # MySQL 데이터 파일
| |____postgresql           # PostgreSQL 데이터 파일
| |____redis                # Redis 데이터 파일
|____etc                    # 설정 파일 디렉터리 (package/etc의 심볼릭 링크)
|____logs                   # 로그 파일 디렉터리 (package/var/log의 심볼릭 링크)
|____package                # 패키지 설치 디렉터리
| |____bin                  # 패키지 실행 파일
| |____common               # 공용 라이브러리 및 개발 라이브러리
| | |____imap-uw
| | |____include            # 헤더 파일 (ServBay Development Library)
| | |____lib                # 공유 및 정적 라이브러리 (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # 패키지 설정 파일 실 저장 위치
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (Python, Go, Java, Ruby, Rust 등)
| |____<package_name>       # 각 패키지 메인 디렉터리
| | |____<major_version>   # 주요 버전 디렉터리
| | | |____<full_version> # 전체 버전 디렉터리 (패키지 본체)
| | | |____current         # 최신 전체 버전 심볼릭 링크
| | |____...
| |____sbin                 # 패키지 시스템 실행 파일
| |____var                  # 패키지 가변 데이터 (예: 로그 실 저장 위치)
| | |____log                # 실제 로그 저장 위치
| | |____run                # 실행시 파일 (예: .pid 파일)
|____sbin                   # 시스템 실행 파일 디렉터리 (package/sbin의 심볼릭 링크)
|____script                 # ServBay 내부 관리 스크립트
|____ssl                    # SSL 인증서 디렉터리
| |____acme                 # ACME 프로토콜로 신청한 SSL 인증서
| |____caddy                # Caddy가 자동 생성하는 SSL 인증서
| |____import               # 사용자가 가져온 서드파티 SSL 인증서
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # 임시 파일 및 소켓 파일 디렉터리
|____www                    # 웹사이트 루트 디렉터리
| |____servbay              # 샘플 웹사이트 디렉터리

각 디렉터리 용도는 아래에서 설명합니다.

ServBay 메인 디렉터리

ServBay 메인 디렉터리는 기본적으로 /Applications/ServBay에 위치하며, ServBay 관련 모든 패키지, 설정 파일, 데이터, 로그가 집약되어 있습니다.

로컬 개발 환경과 데이터 보호를 위해, 해당 메인 디렉터리를 정기적으로 백업하는 것이 좋습니다. Time Machine 등 백업 툴로 /Applications/ServBay 전체를 저장하면 안전하게 관리할 수 있습니다.

웹사이트 루트 디렉터리(www)

웹사이트 파일은 /Applications/ServBay/www가 메인 디렉터리입니다. 모든 로컬 프로젝트 파일을 여기서 관리하세요.

구조의 명확성과 관리 편의를 위해, 각 웹사이트(ServBay에서 "사이트"로 부름)마다 개별 서브 폴더를 만드는 것이 강력히 권장됩니다.

예를 들어, web.servbay.demo, api.servbay.demo, new.servbay.local 사이트를 구성했다면 추천 디렉터리 구조는 다음과 같습니다:

/Applications/ServBay/www
|____servbay.demo           # *.servbay.demo 관련 사이트 저장
| |____web               # web.servbay.demo의 사이트 파일
| |____api               # api.servbay.demo의 사이트 파일
|____servbay.local          # *.servbay.local 관련 사이트 저장
| |____new               # new.servbay.local의 사이트 파일
|____myproject              # 기타 독립 프로젝트(예: myproject.local)

이 구조 덕분에 각 프로젝트와 도메인을 구분하기 쉽고, 관리도 효율적으로 진행할 수 있습니다.

설정 파일 디렉터리(etc)

설정 파일 디렉터리 /Applications/ServBay/etc는 실제로 /Applications/ServBay/package/etc로 연결된 심볼릭 링크입니다. ServBay에 설치된 모든 패키지(PHP, MariaDB, Nginx, Caddy 등)의 주요 설정 파일이 이곳에 저장됩니다.

일상적으로 해당 경로(/Applications/ServBay/etc)를 통해 설정 파일을 직접 편집할 수 있습니다. 설정 변경시 대부분의 서비스는 재시작이 필요합니다.

아래는 주요 패키지별 설정 파일 예시입니다:

PHP(etc/php)

PHP 설정 디렉터리는 버전별 체계를 갖추고 있습니다. 예를 들어, etc/php에는 5.6, 7.4, 8.3 등 디렉터리가 있고, 각 디렉터리는 PHP의 대버전을 나타냅니다. 구조는 다음과 같습니다:

php
|____5.6                    # PHP 5.6 설정
| |____conf.d               # 확장 설정 파일
| |____php.ini              # PHP 메인 설정 파일
|____7.4                    # PHP 7.4 설정
| |____conf.d               # 확장 설정 파일
| |____php-fpm.d            # PHP-FPM 풀 설정 디렉터리
| |____php-fpm.conf         # PHP-FPM 메인 설정 파일
| |____php.ini              # PHP 메인 설정 파일
|____8.3                    # PHP 8.3 설정
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (기타 PHP 버전)

각 버전 폴더에 php.ini(메인 설정), php-fpm.conf(PHP-FPM 메인 설정, 지원하는 경우), pear.conf 등이 포함됩니다. 해당 파일 변경 후에는 ServBay 컨트롤 패널이나 servbayctl 명령어로 PHP-FPM 서비스를 재시작해야 변경 사항이 반영됩니다.

conf.d는 PHP 확장 설정 디렉터리로, xdebug.ini, opcache.ini, redis.ini 등 각종 확장 설정 파일이 들어 있습니다. 편집 후에도 동일하게 서비스 재시작이 필요합니다.

참고: ServBay는 작은 버전(PHP 8.3.3, 8.3.5 등)이 같은 대버전(etc/php/8.3) 설정 파일을 공유하도록 설계됐습니다.

MariaDB / MySQL / PostgreSQL(etc/mariadb, etc/mysql, etc/postgresql)

데이터베이스 설정 파일도 버전별로 분류되어 있습니다. 예를 들어, etc/mariadb/11.2처럼 이름이 붙으며, 해당 폴더에는 주 설정 파일(my.cnf나 postgresql.conf)이 존재합니다. 변경 후에는 서비스 재시작이 필요하며, 동일 대버전끼리는 설정을 공유합니다.

root 사용자 비밀번호 초기화는 설정 파일을 직접 수정하지 않고, 명령어 도구나 ServBay 컨트롤 패널 기능을 이용해야 합니다.

Caddy(etc/caddy)

Caddy의 설정 파일(Caddyfile)은 etc/caddy에 위치합니다.

중요: ServBay는 컨트롤 패널에서 사이트 정보를 토대로 Caddyfile을 자동 생성합니다. 직접 수정하지 마세요. 변경하면 다음 설정 파일 생성 시 덮어쓰기 됩니다. 커스텀 설정이 필요하다면 ServBay 컨트롤 패널 사이트 설정에서 추가하세요.

Nginx(etc/nginx)

Nginx 메인 설정 파일(nginx.conf)은 etc/nginx에 있습니다. ServBay 또한 사이트 설정에 따라 자동으로 설정 파일을 생성하거나 포함시킵니다. 직접 수정 시에는 주의가 필요하며, 가급적 컨트롤 패널을 이용해 관리하세요.

dnsmasq(etc/dnsmasq)

dnsmasq 설정 디렉터리엔 dnsmasq.conf(기본 설정 파일)과 domains.conf(로컬 도메인 정보 자동 생성)가 포함됩니다.

중요: 이 두 파일은 ServBay가 자동 관리하며, 직접 수정하지 마세요. 잘못 수정하면 로컬 사이트 접속에 문제가 발생할 수 있습니다.

기타 패키지 설정

Node.js, Python, Go, Java, Ruby, Rust 등 지원 패키지의 전역 및 서비스 설정 파일도 etc 하위 디렉터리에 저장됩니다. 버전별 구조를 따릅니다.

ServBay 내부 데이터 디렉터리(data/servbay)

/Applications/ServBay/data/servbay

이 디렉터리는 ServBay 정상 동작에 꼭 필요한 핵심 설정 파일, 상태 정보, 사용자 특화 세팅 등 애플리케이션 자체 데이터가 저장됩니다. 컨트롤 패널, 패키지 관리, 사이트 및 데이터베이스 설정 등에 반드시 쓰입니다.

중요: 반드시 백업하고, 파일을 직접 삭제‧수정하지 마세요. 잘못하면 ServBay가 실행되지 않거나 설정 손실이 발생할 수 있습니다.

실행 파일 및 스크립트 디렉터리(bin, sbin, script)

/Applications/ServBay/bin -> package/bin
/Applications/ServBay/sbin -> package/sbin
/Applications/ServBay/script

모든 실행 파일은 bin, sbin에 정리되어 있고, 두 디렉터리는 실제로 package/bin, package/sbin을 가리키는 심볼릭 링크입니다. ServBay가 통합한 각종 도구와 언어 런타임이 포함됩니다.

ServBay는 해당 디렉터리를 시스템 PATH 환경변수에 자동 등록하므로, 터미널에서 바로 실행할 수 있습니다. 주요 항목은 다음과 같습니다:

• 주요 도구: curl, openssl, frpc 등
• 언어 런타임: php(기본 버전), php-5.6, php-7.4, php-8.3, node(기본), node-16, node-18, python3, go, java, ruby, rustc 등. 명령어에 버전을 명시하여 원하는 버전을 선택 사용 가능
• DB 클라이언트: mysql, psql, mongosh, redis-cli 등

script 디렉터리(/Applications/ServBay/script)에는 ServBay 내부 서비스 관리 또는 데이터베이스 초기화, 유지보수 작업을 위한 스크립트가 포함되어 있습니다. 직접 실행할 수 있으나, 보통은 ServBay의 servbayctl 커맨드 툴을 이용하는 것이 더 편리합니다. 이 툴은 핵심 관리 스크립트들을 포괄적으로 제공합니다.

예시 : PHP 7.4 FPM 서비스를 시작할 경우

servbayctl start php 7.4

servbayctl는 /Applications/ServBay/bin에 위치합니다.

데이터베이스 파일 디렉터리(db)

/Applications/ServBay/db

각종 데이터베이스 프로그램이 실제 데이터 파일을 저장하는 자리입니다. 설정 파일과 마찬가지로, 패키지 종류와 버전별로 구성되어 있습니다.

• /Applications/ServBay/db/mariadb/<major_version>: MariaDB 데이터 파일
• /Applications/ServBay/db/mysql/<major_version>: MySQL 데이터 파일
• /Applications/ServBay/db/postgresql/<major_version>: PostgreSQL 데이터 파일
• /Applications/ServBay/db/mongodb: MongoDB 데이터 파일
• /Applications/ServBay/db/redis: Redis 데이터 파일

각 DB 소프트웨어는 대버전별로 데이터 파일을 공유합니다. 예를 들어 MariaDB 11.2.x 전체는 /Applications/ServBay/db/mariadb/11.2 아래 같은 파일을 사용합니다.

중요: 모든 로컬 DB 데이터가 이 위치에 있으므로, 버전 업그레이드나 시스템 마이그레이션 등 중요 작업 전에는 /Applications/ServBay/db 전체 백업이 필수입니다. ServBay의 자동 백업 기능도 DB 백업을 포함합니다.

로그 디렉터리(logs)

/Applications/ServBay/logs -> package/var/log

ServBay는 통합 서비스 로그를 /Applications/ServBay/logs에 집중 관리합니다. 이 디렉터리는 /Applications/ServBay/package/var/log의 심볼릭 링크입니다. 각 서비스 런타임, 오류 상황을 한눈에 파악할 수 있습니다.

로그 파일은 서비스별 하위 폴더로 정리됩니다:

• logs/caddy/, logs/nginx/: Caddy, Nginx의 접근/에러 로그(도메인별 서브폴더)
• logs/php/: PHP-FPM 로그(php-fpm.log) 및 PHP 에러 로그(errors.log). errors.log는 프레임워크나 앱에서 처리하지 못한 치명적 에러 위주로 기록됩니다.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: 각 DB의 에러, 슬로우 쿼리 등
• 기타 Python, Go, Java, Ruby, Rust 등 서비스 로그는 서비스별 폴더에 저장됩니다.

참고: 접근‧에러 로그는 프로젝트에 따라 대용량이 될 수 있으므로, 디스크 사용량 점검과 정기 삭제를 권장합니다.

패키지 디렉터리(package)

/Applications/ServBay/package

ServBay가 모든 패키지를 실제로 설치, 관리하는 위치입니다. 각 패키지는 패키지명/대버전/전체버전 구조로 정리됩니다. 예를 들어 PHP 특정 버전은 /Applications/ServBay/package/php/8.3/8.3.7에 설치됩니다.

컨트롤 패널로 간편하게 패키지 설치, 삭제, 버전 전환이 가능합니다.

구형 버전 패키지는 필요없다면, 전체버전 폴더(/Applications/ServBay/package/php/8.2/8.2.10 등)를 직접 삭제해 디스크를 절약할 수 있습니다.

중요: 각 패키지 대버전 디렉터리(예: /Applications/ServBay/package/php/8.3)엔 current라는 심볼릭 링크가 존재, 최신/활성버전 폴더로 연결됩니다. current 심볼릭 링크를 삭제 또는 수정하지 마세요. 잘못하면 서비스 실행파일이나 라이브러리를 찾지 못해 실행 장애가 발생합니다.

SSL 인증서 디렉터리(ssl)

/Applications/ServBay/ssl

SSL/TLS 관련 인증서 파일을 저장하는 디렉터리입니다. 주요 내용은 다음과 같습니다:

• ServBay가 로컬 사이트용으로 ACME 프로토콜로 자동 발급받은 SSL 인증서(ssl/caddy 또는 ssl/acme 하위).
• ServBay가 생성한 로컬 HTTPS 개발용 루트 인증서(User CA) 및 공개 인증서(Public CA)는 ssl/private, ssl/public 아래에 있습니다. 해당 CA를 시스템 신뢰 저장소에 추가하면, 브라우저에서 ServBay가 발급한 로컬 사이트 인증서를 신뢰해 HTTPS 경고가 사라집니다.

백업 디렉터리(backup)

/Applications/ServBay/backup

ServBay의 내장 자동 백업 기능이 결과물을 여기에 저장합니다. 주요 백업 대상:

• backup/config: ServBay 핵심 및 패키지 설정 파일
• backup/databases: MariaDB, MySQL, PostgreSQL, MongoDB 등 DB 데이터
• backup/ssl: SSL 인증서 파일
• backup/websites: /Applications/ServBay/www에 저장된 웹사이트 프로젝트 파일

정기적으로 해당 디렉터리를 확인하고, 필요시 외부 저장소로 이전해 더 완벽한 데이터 재해복구 전략을 세우세요.

임시 파일 디렉터리(tmp)

/Applications/ServBay/tmp

각 서비스가 런타임 시 생성하는 임시 파일을 담는 곳입니다. 대표적으로 .pid와 소켓 파일이 존재합니다.

• .pid 파일: 실행 중인 서비스 프로세스 ID 기록용
• 소켓 파일: php-cgi.sock, mysql.sock, pgsql.sock 등. 프로세스 간 로컬 소켓(Unix Domain Socket) 통신에 쓰입니다. TCP 포트 연결보다 속도와 성능이 좋고, 딜레이도 낮으므로, 같은 머신에서 동작하는 서비스에 특히 적합합니다.

공용 컴포넌트 및 개발 라이브러리(package/common)

/Applications/ServBay/package/common

ServBay가 설치한 패키지들이 의존하는 공용 컴포넌트, 공유 라이브러리(*.dylib), 선택적 개발 라이브러리를 담는 곳입니다.

ServBay Development Library(컴파일용 종속성 패키지)를 설치하면, 이 위치에 include(헤더 파일), lib(정적 라이브러리 *.a, 링크 라이브러리 *.la) 폴더도 추가됩니다. PHP 확장 등 소스에서 컴파일할 때 이 파일들이 유용합니다.

중요: package/common/lib 하에 *.dylib 파일은 삭제하지 마세요. ServBay 통합 패키지가 정상 구동에 꼭 필요하며, 삭제하면 의존성 부족으로 오류가 발생할 수 있습니다.

요약

ServBay의 디렉터리 구조는 패키지, 설정, 데이터, 로그, 웹사이트 파일을 명확히 분리하여, 표준 Unix 파일 시스템 구조를 반영합니다. 덕분에 개발자는 로컬 환경을 직관적으로 관리할 수 있습니다. 각 디렉터리 용도에 익숙해지면 ServBay를 활용한 웹 개발의 효율성‧편의성이 크게 높아집니다. 특히 data, db 등 핵심 디렉터리 정기 백업은 개발 작업을 보호하는 중요한 습관입니다.