Detailed Guide to ServBay Directory Structure

Overview

ServBay is a local web development environment for both macOS and Windows, featuring a streamlined and well-organized directory structure. If you're familiar with Linux/Unix systems, you'll find its file organization similar to standard filesystem layouts, making it easier for developers to quickly locate and manage various files.

ServBay Installation Location

Default installation paths for ServBay on different platforms:

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

Understanding ServBay's directory structure is crucial for efficient local development, environment configuration, troubleshooting, and data backup. This article explains the main directories and their purposes in detail.

A typical ServBay installation directory structure looks like:

ServBay
|____backup                 # Backup files directory
| |____config               # Configuration backup
| |____databases            # Database backup
| |____ssl                  # SSL certificate backup
| |____websites             # Website files backup
|____bin                    # User-executable files (symlinked to package/bin)
|____data                   # ServBay internal data directory
| |____servbay              # ServBay core configs and data
|____db                     # Database file storage directory
| |____mariadb              # MariaDB data files
| |____mongodb              # MongoDB data files
| |____mysql                # MySQL data files
| |____postgresql           # PostgreSQL data files
| |____redis                # Redis data files
|____etc                    # Configuration files directory (symlinked to package/etc)
|____logs                   # Log files directory (symlinked to package/var/log)
|____package                # Software packages installation directory
| |____bin                  # Executable files within packages
| |____common               # Shared libraries and dev libraries
| | |____imap-uw
| | |____include            # Header files (ServBay Development Library)
| | |____lib                # Shared and static libraries (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Actual storage for package configs
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (configs for other packages like Python, Go, Java, Ruby, Rust, etc)
| |____<package_name>       # Main directory for each package
| | |____<major_version>    # Major version directory
| | | |____<full_version>   # Full version directory (actual package files)
| | | |____current          # Symlink to the latest full version
| | |____...
| |____sbin                 # System-executable files within packages
| |____var                  # Package variable data (like actual logs location)
| | |____log                # Actual log files location
| | |____run                # Runtime files (e.g., .pid files)
|____sbin                   # System-executable files (symlinked to package/sbin)
|____script                 # ServBay internal management scripts
|____ssl                    # SSL certificates directory
| |____acme                 # SSL certificates obtained via ACME
| |____caddy                # SSL certificates auto-generated by Caddy
| |____import               # Third-party SSL certificates imported by users
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Temporary files and socket files
|____www                    # Website root directory
| |____servbay              # Example website directory

Below is a detailed explanation of each directory's function.

ServBay Root Directory

The ServBay root directory is typically located at /Applications/ServBay. All ServBay-related packages, configurations, data, logs, and more are stored 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 use Time Machine or other backup tools to take full backups of /Applications/ServBay.

Website Root Directory (www)

The main directory for website files is /Applications/ServBay/www. This is where you store all your local website project files.

For clean organization and easier management, it's recommended to create a separate subfolder for each independent site or virtual host (referred to as "websites" in ServBay) under this directory.

For example, if you've created sites like web.servbay.demo, api.servbay.demo, and new.servbay.local, the recommended directory structure would be:

/Applications/ServBay/www
|____servbay.demo           # Websites related to *.servbay.demo domain
| |____web               # Files for web.servbay.demo
| |____api               # Files for api.servbay.demo
|____servbay.local          # Websites related to *.servbay.local domain
| |____new               # Files for new.servbay.local
|____myproject              # Other standalone projects, e.g., myproject.local

This structure helps separate different projects and domains, making management more convenient.

Configuration Directory (etc)

The configuration directory /Applications/ServBay/etc is a symlink pointing to /Applications/ServBay/package/etc. This is where all ServBay-installed package configurations (such as PHP, MariaDB, Nginx, Caddy, etc.) are stored.

In daily use, you can access and edit configuration files directly via /Applications/ServBay/etc. Most configuration changes require the respective service to be restarted to take effect.

Below are examples for some common package configuration locations:

PHP (etc/php)

PHP configuration uses a double-layered structure to distinguish major PHP versions. For example, under etc/php, you'll find directories like 5.6, 7.4, 8.3, each representing a major PHP version. Typical structure:

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 directory contains php.ini (main config), php-fpm.conf (if supported), pear.conf, etc. After editing these files, restart the matching PHP-FPM service using the ServBay Control Panel or the servbayctl command to apply changes.

The conf.d directory holds PHP extension configs, including files like xdebug.ini, opcache.ini, redis.ini, etc. Editing these files enables, disables, or configures PHP extensions. Restart the PHP-FPM service after making changes.

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

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

Database configuration directories also use versioning, e.g., etc/mariadb/11.2. Main configuration files like MariaDB/MySQL's my.cnf and PostgreSQL's postgresql.conf are found here. Edits require a database service restart to take effect. Similar to PHP, all minor versions within a major version share the same configuration.

Resetting the root password for MariaDB, MySQL, or PostgreSQL is typically done via specific CLI tools or the ServBay Control Panel, not by directly editing configs.

Caddy (etc/caddy)

Caddy’s configuration file (Caddyfile) resides in etc/caddy.

Important: ServBay automatically generates Caddyfile based on your website settings in the Control Panel. Do not manually edit this file, as any changes will be overwritten when ServBay next regenerates the config. To add custom Caddy settings for specific sites, use the ServBay Control Panel.

Nginx (etc/nginx)

The main Nginx config file, nginx.conf, is found under etc/nginx. Similar to Caddy, ServBay automatically generates site-specific configs. If you edit the main config file manually, do so with caution; usually, it’s best to manage website configs via the ServBay Control Panel.

dnsmasq (etc/dnsmasq)

The dnsmasq config directory includes dnsmasq.conf (default config) and domains.conf (generated by ServBay from your local domain settings).

Important: Both dnsmasq.conf and domains.conf are auto-generated and managed by ServBay to ensure proper local domain resolution. Do not edit these files manually, as this may prevent access to local websites.

Other Package Configurations

Other supported packages like Node.js, Python, Go, Java, Ruby, Rust, etc., place global or service-level configs under their respective subdirectories in etc, following similar version-based structure.

ServBay Internal Data Directory (data/servbay)

/Applications/ServBay/data/servbay

This directory stores key configuration files, status info, and user-specific settings essential for ServBay’s operation. These files underpin the Control Panel, package management, site/database configs, and more.

Important: Back up this directory regularly. Do not manually delete or modify any files here, as this may cause ServBay to fail to start or lose configurations.

Executable Files & Scripts Directory (bin, sbin, script)

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

All ServBay executables are organized in bin and sbin, which are symlinks to package/bin and package/sbin. These directories include integrated tools and language runtimes.

You can access these executables directly in the terminal, as ServBay adds these directories to your system PATH during startup. Includes:

• Common tools: like curl, openssl, frpc, etc.
• Multiple version runtimes: like php (default), php-5.6, php-7.4, php-8.3, node (default), node-16, node-18, python3, go, java, ruby, rustc, etc. To use specific versions, use the versioned command.
• Database clients: e.g., mysql, psql, mongosh, redis-cli.

The script directory (/Applications/ServBay/script) contains internal management scripts for starting/stopping services, initializing databases, maintenance tasks, etc. While you can run these scripts directly, it’s recommended to use the servbayctl CLI tool, which wraps these scripts and provides an easier interface.

For example, to start PHP 7.4 FPM:

servbayctl start php 7.4

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

Database Files Directory (db)

/Applications/ServBay/db

This is where actual data files for all ServBay-installed databases are stored. Like configuration files, database data is organized by software type and version:

• /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 uses a single data directory per major version for each database. For example, all MariaDB 11.2.x versions use /Applications/ServBay/db/mariadb/11.2 for data storage.

Important: This directory stores all your local database data. Always back up /Applications/ServBay/db before major operations (like upgrading ServBay, system migration, etc). ServBay’s auto-backup feature also includes database file backups.

Logs Directory (logs)

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

All integrated service logs are consolidated in /Applications/ServBay/logs, which is a symlink to /Applications/ServBay/package/var/log. This helps developers monitor service status and errors conveniently.

Logs are typically organized per service in subdirectories, for example:

• logs/caddy/ or logs/nginx/: Caddy or Nginx access & error logs, usually organized by domain name in subfolders.
• logs/php/: PHP-FPM logs (php-fpm.log) and PHP error logs (errors.log). errors.log primarily records fatal errors not handled by frameworks or applications.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: Service error logs, slow query logs, etc.
• Other services: logs for Python, Go, Java, Ruby, Rust, etc., in their respective subdirectories.

Note: Log files, especially access and error logs, can consume significant disk space in active projects. Periodically check and clean unnecessary logs to save space.

Packages Directory (package)

/Applications/ServBay/package

This is the actual location where ServBay installs and manages all packages. Each package has its own directory, typically organized as package_name/major_version/full_version. For instance, a PHP version might be installed at /Applications/ServBay/package/php/8.3/8.3.7.

Packages can be installed, uninstalled, and upgraded via the ServBay Control Panel.

You can manually delete outdated full version directories (e.g., /Applications/ServBay/package/php/8.2/8.2.10) for obsolete packages to free disk space.

Important: Each package major version directory (e.g., /Applications/ServBay/package/php/8.3) usually contains a current symlink to the current or latest minor version full directory. Do NOT manually delete or modify the current symlinks, as this may prevent ServBay from locating executables or libraries, causing services to fail.

SSL Certificates Directory (ssl)

/Applications/ServBay/ssl

This directory stores SSL/TLS certificates, including:

• SSL certificates automatically requested via ACME for your local sites (usually under ssl/caddy or ssl/acme, depending on the web server used).
• Root and public certificates for local HTTPS development (ServBay User CA and Public CA), typically in ssl/private and ssl/public. Installing these CA certificates to your system trust store allows browsers to trust ServBay-signed certificates, avoiding HTTPS warnings.

Backup Directory (backup)

/Applications/ServBay/backup

ServBay’s built-in auto-backup feature stores backup files here, allowing you to easily back up key development data and configurations, including:

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

Periodically check this directory and consider migrating backup files to external drives for better disaster recovery.

Temporary Files Directory (tmp)

/Applications/ServBay/tmp

This directory contains temporary files generated during service runtime, commonly .pid files and communication socket files.

• .pid files: record process IDs for running services.
• Socket files: e.g., php-cgi.sock, mysql.sock, pgsql.sock, etc. These files facilitate communication between local processes and services like php-fpm or databases using Unix Domain Sockets, offering higher throughput, better performance, and lower latency than TCP for communication on the same machine.

Shared Components & Development Library (package/common)

/Applications/ServBay/package/common

This directory includes shared components and libraries (*.dylib) used by ServBay packages, plus optional development libraries.

If you install the ServBay Development Library (optional package for compilation dependencies), you'll also find the include directory (header files) and lib directory (static libs *.a, link libs *.la). These are useful for compiling PHP extensions from source or other programs that depend on ServBay’s bundled libraries.

Important: Do NOT manually delete any *.dylib files from package/common/lib; they are required for normal operation, and their removal will cause runtime errors due to missing dependencies.

Summary

ServBay's directory structure clearly separates packages, configs, data, logs, and website files, following the conventions of standard Unix filesystems. This makes it intuitive for developers to manage their local environment. Familiarity with these directories will greatly boost your efficiency and convenience when developing web projects with ServBay. Regular backups of key directories (especially data and db) are crucial to protecting your development workflow from potential data loss.