In-Depth Guide to the ServBay Directory Structure

ServBay is a local web development environment designed specifically for macOS, featuring an organized and minimalist directory structure. If you’re familiar with Linux/Unix systems, you’ll notice that ServBay’s file organization closely follows standard filesystem conventions—helping developers to quickly locate and manage various files.

Understanding the ServBay directory structure is crucial for efficient local development, environment configuration, troubleshooting, and backing up your data. This document walks you through ServBay’s primary directories and their purposes.

A typical ServBay installation directory structure looks like this:

ServBay
|____backup                 # Backup files directory
| |____config               # Configuration backups
| |____databases            # Database backups
| |____ssl                  # SSL certificate backups
| |____websites             # Website file backups
|____bin                    # User-executable files (symlink to package/bin)
|____data                   # Internal data directory for ServBay
| |____servbay              # Core ServBay configs and data
|____db                     # Database data storage directory
| |____mariadb              # MariaDB data files
| |____mongodb              # MongoDB data files
| |____mysql                # MySQL data files
| |____postgresql           # PostgreSQL data files
| |____redis                # Redis data files
|____etc                    # Config files directory (symlink to package/etc)
|____logs                   # Logs directory (symlink to package/var/log)
|____package                # Packages installation directory
| |____bin                  # Executable files from packages
| |____common               # Shared and development libraries
| | |____imap-uw
| | |____include            # Header files (ServBay Development Library)
| | |____lib                # Shared & static libs (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Actual storage for package configs
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (other package configs such as Python, Go, Java, Ruby, Rust, etc.)
| |____<package_name>       # Root of each package
| | |____<major_version>   # Major version directory
| | | |____<full_version> # Full version directory (contains package files)
| | | |____current         # Symlink to the latest full version
| | |____...
| |____sbin                 # Package system executables
| |____var                  # Variable data for packages (e.g., logs)
| | |____log                # Actual log storage
| | |____run                # Runtime files (e.g., .pid files)
|____sbin                   # System executable files (symlink to package/sbin)
|____script                 # ServBay internal management scripts
|____ssl                    # SSL certificate directory
| |____acme                 # SSL certs via ACME protocol
| |____caddy                # Auto-generated Caddy SSL certs
| |____import               # User-imported third-party SSL certificates
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Temp files and socket files
|____www                    # Web root directory
| |____servbay              # Example website directory

Below, we’ll break down the purpose of each directory in detail.

ServBay Root Directory

By default, the ServBay root directory is located at /Applications/ServBay. All ServBay-related packages, configs, data, logs, and more are consolidated here.

To ensure the safety of your local development environment and data, it’s highly recommended to back up this root directory regularly. You can do this using Time Machine or any other backup tool to comprehensively back up the /Applications/ServBay directory.

Web Root (www)

Your main web project directory is at /Applications/ServBay/www. All local website project files should be stored here.

For clarity and ease of management, it’s strongly recommended to create a separate subfolder under this directory for each website project or virtual host (called "websites" in ServBay).

For example, if you create web.servbay.demo, api.servbay.demo, and new.servbay.local sites, they should be organized as follows:

/Applications/ServBay/www
|____servbay.demo           # All *.servbay.demo domains
| |____web               # web.servbay.demo website files
| |____api               # api.servbay.demo website files
|____servbay.local          # All *.servbay.local domains
| |____new               # new.servbay.local website files
|____myproject              # Other standalone projects, like myproject.local

This structure helps you clearly separate different projects and domains, making management easier.

Configuration Files (etc)

The /Applications/ServBay/etc directory is a symlink to /Applications/ServBay/package/etc. This is where ServBay stores the main config files for all installed packages (such as PHP, MariaDB, Nginx, Caddy, and more).

You can directly access and edit configuration files at /Applications/ServBay/etc. After modifying most config files, you’ll usually need to restart the relevant service for changes to take effect.

Common config file locations include:

PHP (etc/php)

PHP config files are structured in two levels, grouped by major PHP version. For example, within etc/php, you’ll find directories like 5.6, 7.4, 8.3, each corresponding to a major PHP version. A typical layout:

php
|____5.6                    # PHP 5.6 config
| |____conf.d               # Extension configs
| |____php.ini              # Main PHP config
|____7.4                    # PHP 7.4 config
| |____conf.d               # Extension configs
| |____php-fpm.d            # PHP-FPM pool configs
| |____php-fpm.conf         # PHP-FPM main config
| |____php.ini              # Main PHP config
|____8.3                    # PHP 8.3 config
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (other PHP versions)

Each version’s directory includes php.ini (main PHP config), php-fpm.conf (main PHP-FPM config, if supported), pear.conf, and more. After making changes, restart the relevant PHP-FPM service via the ServBay control panel or servbayctl for new settings to apply.

The conf.d directory contains extension configs, including xdebug.ini, opcache.ini, redis.ini, etc. Edit these to load, unload, or change settings for PHP extensions, then restart the PHP-FPM service as needed.

Note: ServBay is designed so that all PHP minor versions under the same major version share config files. For example, both PHP 8.3.3 and 8.3.5 use the etc/php/8.3 directory for their configs.

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

Config directories for database software are also organized by version (e.g., etc/mariadb/11.2). Within these folders, you'll typically find the main config file (my.cnf for MariaDB/MySQL, postgresql.conf for PostgreSQL). Changes require restarting the corresponding database service. All minor versions under the same major version share the same config set.

Resetting the root password for MariaDB, MySQL, or PostgreSQL is usually done via command-line tools or the ServBay control panel, not by editing configuration files directly.

Caddy (etc/caddy)

Caddy’s config file (Caddyfile) is located under etc/caddy.

Important: ServBay automatically generates the Caddyfile based on the "websites" configured in the control panel. Do not manually edit this file, as your changes may be overwritten the next time ServBay updates it. To add custom Caddy configs for a specific site, use the website settings in the ServBay control panel.

Nginx (etc/nginx)

Nginx’s main config (nginx.conf) is in etc/nginx. As with Caddy, ServBay generates or includes website configurations automatically based on your site setup. Edit the main config file with care—site management is best handled through the control panel.

dnsmasq (etc/dnsmasq)

The dnsmasq config directory contains dnsmasq.conf (default settings) and domains.conf (auto-generated by ServBay for your local domains).

Important: Both dnsmasq.conf and domains.conf are auto-generated and managed by ServBay to ensure proper local DNS functionality. Do not edit these files manually, or your local sites may become inaccessible.

Other Package Configurations

For other packages supported by ServBay, such as Node.js, Python, Go, Java, Ruby, Rust, and others, any global or service-level configs are also found in the relevant subfolders under etc, following the same version-based organization.

ServBay Internal Data (data/servbay)

/Applications/ServBay/data/servbay

This directory stores key configuration files, state information, and user-specific settings necessary for ServBay to run. These files are critical for the control panel’s functionality, package management, site, and database configurations.

Important: Back up this directory. Do not delete or modify any files here manually, as this can prevent ServBay from starting or cause configuration loss.

Executable Files and Scripts (bin, sbin, script)

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

All ServBay executables are in bin and sbin (symlinks to package/bin and package/sbin). These include tools and interpreter runtimes integrated with ServBay.

These directories are automatically added to your system PATH (usually on ServBay startup), so you can run executables from the terminal directly. For example:

• Useful tools: curl, openssl, frpc, etc.
• Multiple language runtimes: php (default), php-5.6, php-7.4, php-8.3, node (default), node-16, node-18, python3, go, java, ruby, rustc, etc. Use specific versions by command name.
• Database clients: mysql, psql, mongosh, redis-cli, and more.

The script directory at /Applications/ServBay/script contains system management scripts for internal use—like starting/stopping services, initializing databases, or maintenance tasks. These underpin ServBay functionality, and while you can run them directly, it’s better to use the servbayctl tool, which provides a friendlier interface.

For example, to start the PHP 7.4 FPM service:

servbayctl start php 7.4

The servbayctl tool is located in /Applications/ServBay/bin.

Database Data (db)

/Applications/ServBay/db

This directory stores actual data files for ServBay-installed database software. Like config files, database data is organized by package type and version. For example:

• /Applications/ServBay/db/mariadb/<major_version>: MariaDB data files
• /Applications/ServBay/db/mysql/<major_version>: MySQL data files
• /Applications/ServBay/db/postgresql/<major_version>: PostgreSQL data files
• /Applications/ServBay/db/mongodb: MongoDB data files
• /Applications/ServBay/db/redis: Redis data files

ServBay is designed so that each database major version shares a data directory. For example, all MariaDB 11.2.x releases use /Applications/ServBay/db/mariadb/11.2 for data.

Important: This directory contains all your local database data. Always make a full backup of /Applications/ServBay/db before major changes (such as upgrading or migrating ServBay). ServBay's auto-backup features also include database backups.

Log Files (logs)

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

All integrated service logs are stored in /Applications/ServBay/logs (a symlink to /Applications/ServBay/package/var/log). This allows you to easily check the status and errors of all running services.

Logs are organized into service-specific subfolders, for example:

• logs/caddy/ or logs/nginx/: Store Caddy or Nginx access/error logs, often grouped by site/domain.
• logs/php/: PHP-FPM logs (php-fpm.log) and PHP runtime error log (errors.log). The errors.log mainly records fatal errors not caught by your framework or app.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: Store the corresponding database service’s error logs, slow query logs, and more.
• Other services: Python, Go, Java, Ruby, Rust, etc., store their logs in the respective subfolders.

Note: Log files, especially access and error logs, can grow quickly—especially for busy development projects. Regularly check and clean up old logs to save disk space.

Package Directory (package)

/Applications/ServBay/package

This is where ServBay installs and manages all software packages. Each package is in its own directory, usually package_name/major_version/full_version. For example, PHP 8.3.7 might be at /Applications/ServBay/package/php/8.3/8.3.7.

Use the ServBay Control Panel to easily install, remove, or switch between package versions.

After upgrading, you can manually remove old versions you no longer need (for example, /Applications/ServBay/package/php/8.2/8.2.10) to save space.

Important: In each package’s major version directory (e.g., /Applications/ServBay/package/php/8.3), there’s typically a current symlink pointing to the currently active or latest minor version. Do not delete or change this current symlink—otherwise, ServBay may not find the required executables or libraries and services may fail to start.

SSL Certificates (ssl)

/Applications/ServBay/ssl

SSL/TLS certificate files are stored here, including:

• SSL certificates automatically generated via the ACME protocol for your local websites (usually under ssl/caddy or ssl/acme, depending on your web server).
• Root and public certificates generated by ServBay for local HTTPS development (ServBay User CA and Public CA), usually found in ssl/private and ssl/public. Once you install these CA certs to your system trust store, browsers will trust ServBay-issued certificates, avoiding HTTPS warnings.

Backup Directory (backup)

/Applications/ServBay/backup

This is where ServBay’s built-in backup feature saves your backups, helping you easily safeguard critical project files and configs, including:

• backup/config: Backups of ServBay core and package configs.
• backup/databases: Database backups for MariaDB, MySQL, PostgreSQL, MongoDB, and more.
• backup/ssl: SSL certificate backups.
• backup/websites: Backups of your website project files from /Applications/ServBay/www.

Regularly review this folder, and consider moving backup files to external storage for enhanced disaster recovery.

Temporary Files (tmp)

/Applications/ServBay/tmp

This directory holds temporary files generated by running services, most commonly PID files and Unix socket files.

• .pid files: Store process IDs of running services.
• Socket files: Such as php-cgi.sock, mysql.sock, pgsql.sock, etc. These enable local programs to communicate with services like php-fpm or databases via Unix domain sockets. Compared to TCP, sockets usually offer higher throughput, better performance, and lower latency for same-host processes.

Common Components & Development Libraries (package/common)

/Applications/ServBay/package/common

This directory contains shared components and libraries used by all ServBay packages, including shared libraries (*.dylib) and optional development libs.

If you’ve installed the ServBay Development Library (optional, for native compilation), this directory also has an include folder for headers, and a lib folder for static libs (*.a) and link archives (*.la). These files are necessary if you want to compile PHP extensions or other software against ServBay’s built-in libraries.

Important: Do not delete any *.dylib files in package/common/lib; they’re necessary for ServBay to operate normally. Removing them will cause missing library errors and may break your environment.

Summary

ServBay's directory structure cleanly separates packages, configuration, data, logs, and web files, following established Unix filesystem conventions—making it straightforward for developers to manage the local environment. Being familiar with the purpose of each directory will greatly improve your efficiency and convenience while developing with ServBay. Frequent backup of critical directories (especially data and db) is a key practice to safeguard your development work against data loss.