Explicación Detallada de la Estructura de Directorios de ServBay

Introducción

ServBay es un entorno local de desarrollo web compatible con macOS y Windows, cuyo diseño de estructura de directorios resulta sencillo y ordenado. Si tienes experiencia en sistemas Linux/Unix, notarás múltiples similitudes en la organización de archivos respecto a los estándares de sistemas de archivos, lo que facilita la localización y gestión de todo tipo de archivos para los desarrolladores.

Ubicación de la instalación de ServBay

Las ubicaciones predeterminadas de instalación de ServBay en cada plataforma son:

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

Comprender la estructura de directorios de ServBay es esencial para desarrollar de manera eficiente, configurar el entorno, solucionar problemas y realizar respaldos de datos. A continuación, se detallan los principales directorios y su objetivo.

Una instalación típica de ServBay tendría la siguiente estructura:

ServBay
|____backup                 # Directorio de archivos de respaldo
| |____config               # Respaldo de configuración
| |____databases            # Respaldo de bases de datos
| |____ssl                  # Respaldo de certificados SSL
| |____websites             # Respaldo de sitios web
|____bin                    # Directorio de ejecutables de usuario (enlace simbólico a package/bin)
|____data                   # Directorio de datos internos de ServBay
| |____servbay              # Datos y configuración principal de ServBay
|____db                     # Almacenamiento de datos de bases de datos
| |____mariadb              # Datos de MariaDB
| |____mongodb              # Datos de MongoDB
| |____mysql                # Datos de MySQL
| |____postgresql           # Datos de PostgreSQL
| |____redis                # Datos de Redis
|____etc                    # Directorio de archivos de configuración (enlace simbólico a package/etc)
|____logs                   # Directorio de registros (enlace simbólico a package/var/log)
|____package                # Directorio de instalación de paquetes
| |____bin                  # Ejecutables de los paquetes
| |____common               # Bibliotecas públicas y de desarrollo
| | |____imap-uw
| | |____include            # Archivos de cabecera (ServBay Development Library)
| | |____lib                # Bibliotecas compartidas y estáticas (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Ubicación real de archivos de configuración de paquetes
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (Configuración de otros paquetes como Python, Go, Java, Ruby, Rust, etc.)
| |____<package_name>       # Directorio principal de cada paquete
| | |____<major_version>   # Directorio de versión principal
| | | |____<full_version> # Directorio de versión completa (incluye el paquete)
| | | |____current         # Enlace simbólico a la versión completa más reciente
| | |____...
| |____sbin                 # Ejecutables de sistema de los paquetes
| |____var                  # Datos variables de los paquetes (como registros reales)
| | |____log                # Ubicación de almacenamiento de registros
| | |____run                # Archivos de tiempo de ejecución (como archivos .pid)
|____sbin                   # Directorio de ejecutables de sistema (enlace simbólico a package/sbin)
|____script                 # Scripts internos de gestión de ServBay
|____ssl                    # Directorio de certificados SSL
| |____acme                 # Certificados SSL solicitados vía protocolo ACME
| |____caddy                # Certificados SSL generados automáticamente por Caddy
| |____import               # Certificados SSL de terceros importados por el usuario
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Directorio de archivos temporales y sockets
|____www                    # Raíz de sitios web
| |____servbay              # Directorio de sitios de ejemplo

A continuación, se explica el uso de cada uno de estos directorios.

Directorio principal de ServBay

La carpeta raíz de ServBay se ubica por defecto en /Applications/ServBay. Aquí se agrupan todos los paquetes, archivos de configuración, datos y registros relacionados.

Para proteger tu entorno de desarrollo local y sus datos, se recomienda realizar respaldos periódicos de este directorio principal. Puedes usar Time Machine u otras herramientas para crear copias completas de /Applications/ServBay.

Raíz de los sitios web (www)

El directorio principal para tus archivos de proyectos web se encuentra en /Applications/ServBay/www. Aquí es donde debes guardar los archivos de todos tus proyectos o sitios web locales.

Para mayor claridad y fácil gestión, se recomienda crear una subcarpeta independiente para cada proyecto o sitio web (virtual, llamado “sitio” en ServBay).

Por ejemplo, si has creado web.servbay.demo, api.servbay.demo y new.servbay.local, la organización sugerida sería:

/Applications/ServBay/www
|____servbay.demo           # Sitios bajo el dominio *.servbay.demo
| |____web               # Archivos de web.servbay.demo
| |____api               # Archivos de api.servbay.demo
|____servbay.local          # Sitios bajo el dominio *.servbay.local
| |____new               # Archivos de new.servbay.local
|____myproject              # Otros proyectos independientes, como myproject.local

Esta estructura ayuda a diferenciar proyectos y dominios, facilitando su administración.

Directorio de archivos de configuración (etc)

El directorio /Applications/ServBay/etc es en realidad un enlace simbólico que apunta a /Applications/ServBay/package/etc. Aquí se almacenan los archivos de configuración principal de todos los paquetes instalados (por ejemplo PHP, MariaDB, Nginx, Caddy, etc.)

En el uso diario, puedes acceder y modificar la configuración directamente en /Applications/ServBay/etc. Tras editar la mayoría de los archivos de configuración, es necesario reiniciar el servicio correspondiente para aplicar los cambios.

A continuación, se detallan ejemplos comunes:

PHP (etc/php)

La configuración de PHP se organiza en dos niveles según la versión principal de PHP. Por ejemplo, dentro de etc/php encontrarás carpetas como 5.6, 7.4, 8.3, cada una correspondiente a una versión principal. Una estructura típica sería:

php
|____5.6                    # Configuración para PHP 5.6
| |____conf.d               # Configuración extendida
| |____php.ini              # Archivo principal de configuración
|____7.4                    # Configuración para PHP 7.4
| |____conf.d               # Configuración extendida
| |____php-fpm.d            # Configuración de pools para PHP-FPM
| |____php-fpm.conf         # Configuración principal de PHP-FPM
| |____php.ini              # Archivo principal de configuración
|____8.3                    # Configuración para PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (Otras versiones de PHP)

En cada versión encontrarás php.ini (configuración principal de PHP), php-fpm.conf (configuración principal de FPM, si aplica), pear.conf, entre otros. Tras modificar estos archivos, reinicia el servicio PHP-FPM usando el panel de control de ServBay o el comando servbayctl para aplicar los cambios.

El subdirectorio conf.d contiene la configuración de extensiones PHP, incluyendo archivos como xdebug.ini, opcache.ini, redis.ini, etc. Modificando estos archivos puedes habilitar, deshabilitar o ajustar extensiones de PHP. Después de editar debes reiniciar el servicio PHP-FPM correspondiente.

Nota: ServBay está diseñado para compartir los archivos de configuración entre versiones menores de una misma versión principal. Por ejemplo, tanto PHP 8.3.3 como 8.3.5 usan la configuración contenida en etc/php/8.3.

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

La configuración de bases de datos también se organiza por versiones, como etc/mariadb/11.2. Dentro de estos directorios puedes encontrar el archivo principal de configuración (my.cnf para MariaDB/MySQL o postgresql.conf para PostgreSQL). Tras editar, es necesario reiniciar el servicio. De nuevo, todas las versiones menores dentro de una misma principal compartirán la misma configuración.

Para restablecer contraseñas de usuarios root en MariaDB, MySQL o PostgreSQL, normalmente no se modifica la configuración directamente, sino que se emplean herramientas de línea de comandos o el panel de ServBay.

Caddy (etc/caddy)

La configuración de Caddy (el archivo Caddyfile) se encuentra en etc/caddy.

Importante: ServBay genera el archivo Caddyfile automáticamente según la configuración de “sitios” en el panel de control. No edites el Caddyfile manualmente, ya que tus cambios pueden ser sobrescritos la próxima vez que ServBay lo regenere. Para personalizar la configuración de Caddy de un sitio específico, realiza los ajustes desde el panel de ServBay.

Nginx (etc/nginx)

El archivo principal de Nginx, nginx.conf, se encuentra en etc/nginx. Al igual que con Caddy, ServBay genera fragmentos de configuración relacionados con tus sitios. Si decides modificarlo manualmente, hazlo con precaución y, preferentemente, administra los sitios desde el panel de ServBay.

dnsmasq (etc/dnsmasq)

El directorio de configuración de dnsmasq contiene dnsmasq.conf (la configuración predeterminada) y domains.conf (generado automáticamente según los dominios locales configurados en ServBay).

Importante: Estos archivos son gestionados automáticamente por ServBay para asegurar el correcto funcionamiento de la resolución de dominios locales. No los modifiques manualmente, ya que podría afectar el acceso a tus sitios locales.

Configuración de otros paquetes

Para otros paquetes soportados, como Node.js, Python, Go, Java, Ruby, Rust, etc., cualquier archivo de configuración global o de servicio estará en el subdirectorio correspondiente dentro de etc, siguiendo una organización por versiones similar.

Directorio interno de datos de ServBay (data/servbay)

/Applications/ServBay/data/servbay

Este directorio guarda los archivos críticos de configuración, información de estado y preferencias del usuario necesarias para el funcionamiento correcto de la aplicación ServBay. Son esenciales para la gestión desde el panel de control, paquete de software y configuración de sitios y bases de datos.

Aviso importante: Mantén copias de seguridad de esta carpeta y no la modifiques ni elimines manualmente, ya que podrías causar errores de inicio en ServBay o pérdida de configuración.

Directorios de ejecutables y scripts (bin, sbin, script)

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

Todos los ejecutables de ServBay se agrupan en las carpetas bin y sbin, que son enlaces simbólicos a package/bin y package/sbin. Aquí encontrarás herramientas integradas y runtimes de diferentes lenguajes.

ServBay añade estos directorios al PATH de sistema al iniciar, permitiéndote acceder a ellos directamente desde la terminal. Por ejemplo:

• Herramientas comunes como curl, openssl, frpc, etc.
• Runtimes de varios lenguajes y versiones: php (por defecto), php-5.6, php-7.4, php-8.3, node (por defecto), node-16, node-18, python3, go, java, ruby, rustc, entre otros. Es posible especificar la versión directamente en el comando.
• Clientes de base de datos: mysql, psql, mongosh, redis-cli, etc.

El directorio script (/Applications/ServBay/script) contiene scripts internos de administración, como los usados para iniciar/detener servicios, inicializar bases de datos o realizar tareas de mantenimiento. Aunque puedes ejecutarlos directamente, se recomienda usar la herramienta servbayctl, que encapsula y simplifica el uso de estos scripts.

Por ejemplo, para iniciar el servicio PHP 7.4 FPM:

servbayctl start php 7.4

La utilidad servbayctl se encuentra en /Applications/ServBay/bin.

Directorio de datos de bases de datos (db)

/Applications/ServBay/db

Aquí se almacenan los archivos reales de datos de cada sistema de base de datos instalado. La organización sigue la misma lógica que la de los archivos de configuración, agrupando por tipo de software y versión. Ejemplos:

• /Applications/ServBay/db/mariadb/<major_version>: datos de MariaDB.
• /Applications/ServBay/db/mysql/<major_version>: datos de MySQL.
• /Applications/ServBay/db/postgresql/<major_version>: datos de PostgreSQL.
• /Applications/ServBay/db/mongodb: datos de MongoDB.
• /Applications/ServBay/db/redis: datos de Redis.

Las versiones menores de una misma versión principal comparten los mismos archivos de datos, por ejemplo, toda la serie MariaDB 11.2.x utiliza /Applications/ServBay/db/mariadb/11.2.

Aviso importante: Este directorio contiene toda tu información de bases de datos locales. Antes de realizar acciones críticas (como actualizar ServBay o migrar tu sistema), realiza un respaldo completo de /Applications/ServBay/db. ServBay incluye esta carpeta en la función de respaldo automático.

Directorio de registros (logs)

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

Todos los registros de servicios integrados se almacenan en /Applications/ServBay/logs, que es un enlace simbólico a /Applications/ServBay/package/var/log. Esto facilita la revisión y monitoreo del estado y errores de cada servicio.

Los registros se organizan por subdirectorios según el tipo de servicio, por ejemplo:

• logs/caddy/ o logs/nginx/: registros de acceso y errores de Caddy o Nginx, habitualmente organizados por dominio.
• logs/php/: registros de PHP-FPM (php-fpm.log) y errores de código PHP (errors.log). El archivo errors.log recopila principalmente errores fatales no gestionados por frameworks o aplicaciones.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: registros de errores, consultas lentas y otros eventos de los respectivos servicios de bases de datos.
• Registros de otros servicios: Python, Go, Java, Ruby, Rust, etc.

Recomendación: Los registros de acceso o errores pueden consumir mucho espacio en disco con proyectos activos. Revisa y limpia periódicamente los archivos innecesarios para liberar espacio.

Directorio de paquetes de software (package)

/Applications/ServBay/package

Este es el directorio donde se instalan y gestionan todos los paquetes de software. Cada paquete se agrupa en una carpeta independiente, siguiendo la estructura nombre/v.principal/v.completa, por ejemplo, una versión de PHP podría estar en /Applications/ServBay/package/php/8.3/8.3.7.

Gracias al panel de control de ServBay, puedes instalar, quitar y alternar versiones fácilmente.

Cuando ya no necesites versiones antiguas tras una actualización, puedes eliminar manualmente la carpeta de la versión correspondiente (por ejemplo, /Applications/ServBay/package/php/8.2/8.2.10) para liberar espacio.

Aviso importante: En cada versión principal hay un acceso directo denominado current que apunta a la versión menor más reciente o activa. No elimines ni modifiques manualmente estos enlaces simbólicos, ya que ServBay puede perder acceso al ejecutable o biblioteca del paquete y el servicio no arrancaría correctamente.

Directorio de certificados SSL (ssl)

/Applications/ServBay/ssl

Este directorio almacena todos los certificados SSL/TLS generados o importados:

• Certificados SSL obtenidos automáticamente para tus sitios locales mediante protocolo ACME (almacenados en ssl/caddy o ssl/acme, según el servidor web).
• Certificados raíz y públicos generados por ServBay para desarrollo HTTPS local (ServBay User CA y ServBay Public CA), almacenados en ssl/private y ssl/public. Instala estos certificados en tu sistema para evitar advertencias HTTPS en tu navegador al trabajar con sitios locales.

Directorio de respaldos (backup)

/Applications/ServBay/backup

Este es el lugar donde ServBay guarda los archivos de las copias de seguridad generadas por su función de respaldo automático. Aquí se almacenan datos clave de desarrollo y configuración, incluyendo:

• backup/config: respaldo de archivos de configuración principal y de paquetes.
• backup/databases: datos de respaldo de bases de datos como MariaDB, MySQL, PostgreSQL, MongoDB, etc.
• backup/ssl: respaldo de certificados SSL.
• backup/websites: respaldo de los archivos de proyectos web almacenados en /Applications/ServBay/www.

Verifica este directorio de forma periódica y traslada los respaldos importantes hacia dispositivos de almacenamiento externo para mejorar tu estrategia de recuperación ante desastres.

Directorio de archivos temporales (tmp)

/Applications/ServBay/tmp

Aquí se almacenan archivos temporales generados durante la operación de los servicios, entre los más comunes están los archivos .pid y los archivos socket necesarios para la comunicación de procesos.

• Archivos .pid: guardan el ID de proceso de cada servicio en ejecución.
• Archivos socket: como php-cgi.sock, mysql.sock, pgsql.sock, entre otros. Permiten la comunicación directa vía Unix Domain Socket entre aplicaciones como PHP-FPM y las bases de datos. Comparado con la comunicación por TCP, el uso de sockets suele proporcionar mejor rendimiento y menor latencia para procesos en la misma máquina.

Componentes comunes y bibliotecas de desarrollo (package/common)

/Applications/ServBay/package/common

Este directorio reúne los componentes compartidos y bibliotecas requeridos por los paquetes de ServBay, incluyendo archivos de biblioteca compartida (*.dylib) y, si tienes instalada la ServBay Development Library, archivos de cabecera (include) y bibliotecas estáticas (lib) necesarias para compilar extensiones de PHP u otro software dependiente.

Aviso importante: No elimines manualmente los archivos *.dylib de package/common/lib, son esenciales para el funcionamiento de los paquetes integrados. Su eliminación provocará errores por falta de dependencias.

Resumen

La estructura de directorios de ServBay separa claramente los paquetes, configuraciones, datos, registros y archivos de los sitios web, siguiendo convenciones estándar de archivos Unix para que los desarrolladores gestionen el entorno local de forma intuitiva. Familiarizarte con el propósito de cada carpeta mejorará notablemente tu eficiencia en el desarrollo web con ServBay. Recuerda respaldar periódicamente los directorios clave, especialmente data y db, para proteger tu trabajo ante posibles pérdidas.