Guía detallada de la estructura de directorios de ServBay

ServBay es un entorno de desarrollo web local diseñado especialmente para macOS, cuya estructura de directorios es simple y bien organizada. Si tienes experiencia con sistemas Linux/Unix, notarás que la disposición de archivos de ServBay adopta muchas convenciones estándar de estos sistemas, facilitando a los desarrolladores la localización y gestión eficiente de todo tipo de archivos.

Comprender la estructura de directorios de ServBay es fundamental para un desarrollo local eficiente, la configuración del entorno, la resolución de problemas y la realización de copias de seguridad. A continuación, te explicamos en detalle los directorios principales de ServBay y su utilidad.

La estructura típica del directorio de instalación de ServBay es la siguiente:

ServBay
|____backup                 # Directorio para archivos de respaldo
| |____config               # Respaldo de configuraciones
| |____databases            # Respaldo de bases de datos
| |____ssl                  # Respaldo de certificados SSL
| |____websites             # Respaldo de archivos de sitios web
|____bin                    # Ejecutables de usuario (enlace simbólico a package/bin)
|____data                   # Datos internos de ServBay
| |____servbay              # Configuración y datos centrales de ServBay
|____db                     # Directorio de almacenamiento de bases de datos
| |____mariadb              # Archivos de datos MariaDB
| |____mongodb              # Archivos de datos MongoDB
| |____mysql                # Archivos de datos MySQL
| |____postgresql           # Archivos de datos PostgreSQL
| |____redis                # Archivos de datos Redis
|____etc                    # Archivos de configuración (enlace simbólico a package/etc)
|____logs                   # Archivos de registro (enlace simbólico a package/var/log)
|____package                # Directorio de instalación de paquetes de software
| |____bin                  # Ejecutables de los paquetes de software
| |____common               # Bibliotecas públicas y de desarrollo
| | |____imap-uw
| | |____include            # Archivos de cabecera (ServBay Development Library)
| | |____lib                # Librerías compartidas y estáticas (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Almacenamiento real de archivos de configuración de los paquetes
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (Configuraciones de otros paquetes como Python, Go, Java, Ruby, Rust, etc.)
| |____<package_name>       # Directorio principal de cada paquete
| | |____<major_version>   # Directorio de la versión principal
| | | |____<full_version> # Directorio de versión completa (contiene el paquete)
| | | |____current         # Enlace simbólico al último full_version
| | |____...
| |____sbin                 # Ejecutables del sistema de los paquetes de software
| |____var                  # Datos variables de los paquetes (por ejemplo, ubicación real de logs)
| | |____log                # Ubicación real de logs
| | |____run                # Archivos de runtime (como archivos .pid)
|____sbin                   # 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 generados por el protocolo ACME
| |____caddy                # Certificados SSL generados automáticamente por Caddy
| |____import               # Certificados SSL de terceros importados por el usuario
| |____private              # CA de usuario de ServBay
| |____public               # CA pública de ServBay
|____tmp                    # Archivos temporales y sockets
|____www                    # Directorio raíz de sitios web
| |____servbay              # Directorio de ejemplo de sitio web

A continuación se detalla la función de cada directorio.

Directorio principal de ServBay

El directorio principal de ServBay se encuentra por defecto en /Applications/ServBay. Todos los paquetes de software, archivos de configuración, datos y registros relacionados con ServBay se almacenan aquí.

Para proteger tu entorno de desarrollo local y tus datos, se recomienda realizar copias de seguridad periódicas de este directorio principal. Puedes utilizar Time Machine u otras herramientas para respaldar completamente el directorio /Applications/ServBay.

Directorio raíz de sitios web (www)

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

Para mantener una estructura ordenada y facilitar la gestión, se recomienda crear una carpeta independiente para cada sitio web o dominio virtual (llamados “sitios web” dentro de ServBay).

Por ejemplo, si has creado web.servbay.demo, api.servbay.demo y new.servbay.local, la estructura recomendada sería:

/Applications/ServBay/www
|____servbay.demo           # Todos los sitios relacionados con *.servbay.demo
| |____web               # Archivos de web.servbay.demo
| |____api               # Archivos de api.servbay.demo
|____servbay.local          # Todos los sitios relacionados con *.servbay.local
| |____new               # Archivos de new.servbay.local
|____myproject              # Otros proyectos independientes, como myproject.local

Esta estructura facilita la distinción de proyectos y dominios, mejorando la gestión.

Directorio de archivos de configuración (etc)

El directorio de configuración /Applications/ServBay/etc es en realidad un enlace simbólico a /Applications/ServBay/package/etc. Aquí es donde todos los paquetes instalados en ServBay (PHP, MariaDB, Nginx, Caddy, etc.) guardan sus archivos de configuración principales.

Durante el uso diario puedes acceder y modificar los archivos de configuración directamente a través de /Applications/ServBay/etc. Recuerda que después de modificar la mayoría de estos archivos es necesario reiniciar el servicio correspondiente para que los cambios tengan efecto.

Ejemplos de estructura para los paquetes más comunes:

PHP (etc/php)

El directorio de configuración de PHP utiliza una estructura de dos niveles para distinguir grandes versiones de PHP. Por ejemplo, en etc/php encontrarás carpetas como 5.6, 7.4, 8.3, donde cada una corresponde a una versión principal de PHP. La estructura típica sería:

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

En cada versión encontrarás archivos como php.ini (configuración principal), php-fpm.conf (configuración de PHP-FPM, si aplica), pear.conf, etc. Recuerda reiniciar el servicio PHP-FPM respectivo desde el panel de control de ServBay o el comando servbayctl tras modificar estos archivos.

El directorio conf.d alberga configuraciones de extensiones de PHP, como xdebug.ini, opcache.ini, redis.ini, etc. Modifica estos archivos para agregar, eliminar o ajustar extensiones. Tras los cambios, reinicia el servicio PHP-FPM correspondiente.

Nota: ServBay está diseñado para que todas las subversiones de una versión principal de PHP compartan la misma configuración. Por ejemplo, PHP 8.3.3 y 8.3.5 usan los archivos presentes en etc/php/8.3.

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

La configuración de las bases de datos también sigue una estructura basada en versiones, por ejemplo etc/mariadb/11.2. Aquí encontrarás archivos de configuración como my.cnf para MariaDB/MySQL y postgresql.conf para PostgreSQL. Recuerda reiniciar el servicio correspondiente tras realizar cambios, y ten presente que todas las subversiones de la misma versión principal utilizan la misma configuración.

Restablecer la contraseña del usuario root en bases de datos como MariaDB, MySQL o PostgreSQL generalmente se realiza a través de herramientas de línea de comandos o desde el panel de control de ServBay, y no mediante la edición directa de archivos de configuración.

Caddy (etc/caddy)

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

Aviso importante: El archivo Caddyfile es generado automáticamente por ServBay dependiendo de la configuración que realices desde el panel de control en la sección "Sitios web". No edites este archivo manualmente, ya que cualquier cambio será sobrescrito la próxima vez que ServBay regenere la configuración. Si deseas agregar configuraciones personalizadas utiliza las opciones disponibles en la configuración del sitio web desde el panel de control de ServBay.

Nginx (etc/nginx)

El archivo principal de configuración de Nginx (nginx.conf) está en etc/nginx. Similar a Caddy, ServBay genera o incluye configuraciones de sitios web automáticamente según la información de los "sitios web". Si decides modificar manualmente la configuración principal, hazlo con precaución; en la mayoría de casos, es recomendable emplear el panel de control para estos fines.

dnsmasq (etc/dnsmasq)

El directorio de configuración de dnsmasq incluye dnsmasq.conf (ajustes por defecto) y domains.conf (archivo generado automáticamente por ServBay según los dominios configurados localmente).

Aviso importante: Ambos archivos, dnsmasq.conf y domains.conf, son generados y gestionados automáticamente por ServBay para garantizar la correcta resolución de dominios locales. No los edites manualmente, ya que podrías provocar que tus sitios locales dejen de funcionar.

Configuración de otros paquetes

Para otros paquetes soportados por ServBay como Node.js, Python, Go, Java, Ruby, Rust, etc., si poseen archivos de configuración a nivel global o de servicio, estos también se almacenan en subdirectorios correspondientes dentro de etc, siguiendo el mismo esquema por versión.

Directorio de datos internos de ServBay (data/servbay)

/Applications/ServBay/data/servbay

Aquí se guardan archivos críticos de configuración, información de estado y ajustes específicos del usuario necesarios para el correcto funcionamiento de la aplicación ServBay. Estos archivos son esenciales para el panel de control, la gestión de paquetes, la configuración de sitios web y bases de datos, entre otros.

Aviso importante: Asegúrate de hacer copias de seguridad periódicas de este directorio. No borres ni alteres estos archivos manualmente, ya que podrías impedir el arranque de ServBay o perder configuraciones importantes.

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 están organizados en los directorios bin y sbin (enlaces simbólicos a package/bin y package/sbin). Aquí se incluyen todas las herramientas integradas, así como los interpretadores y entornos de cada lenguaje.

Estos ejecutables están accesibles directamente desde la terminal, ya que ServBay añade estos directorios al entorno PATH del sistema durante su arranque. Algunos ejemplos:

• Herramientas generales: curl, openssl, frpc, etc.
• Ejecutables de lenguajes en diferentes versiones: php (predeterminado), php-5.6, php-7.4, php-8.3, node (predeterminado), node-16, node-18, python3, go, java, ruby, rustc, etc. Puedes llamar una versión específica añadiendo el número de versión en el comando.
• Clientes de base de datos: mysql, psql, mongosh, redis-cli, etc.

El directorio script (/Applications/ServBay/script) contiene scripts internos de ServBay para gestión del sistema, como tareas de inicio/parada de servicios, inicialización de bases de datos, operaciones de mantenimiento, entre otros. Aunque puedes ejecutarlos manualmente, generalmente se recomienda usar la herramienta servbayctl, que ofrece una interfaz más amigable.

Por ejemplo, para iniciar el servicio PHP 7.4 FPM puedes ejecutar:

servbayctl start php 7.4

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

Directorio de archivos de bases de datos (db)

/Applications/ServBay/db

Este directorio almacena los datos de todas las bases de datos instaladas mediante ServBay. Al igual que los archivos de configuración, los datos aquí se organizan por tipo y versión:

• /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.

ServBay organiza los archivos de datos para que todas las subversiones de una versión principal compartan los mismos datos, por ejemplo, la serie MariaDB 11.2.x usará /Applications/ServBay/db/mariadb/11.2.

Aviso importante: Este directorio contiene todas tus bases de datos locales. Antes de realizar cualquier operación importante (como actualizaciones o migraciones del sistema), realiza una copia de seguridad completa del directorio /Applications/ServBay/db. El sistema de respaldo automático de ServBay también incluye estos datos.

Directorio de logs (logs)

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

Todos los registros de los servicios de ServBay se almacenan en /Applications/ServBay/logs, una carpeta enlazada a /Applications/ServBay/package/var/log. Esto facilita a los desarrolladores la revisión del estado y errores de los servicios.

Los archivos de logs suelen organizarse en subdirectorios por tipo de servicio. Ejemplos:

• logs/caddy/ o logs/nginx/: registros de acceso y errores de Caddy o Nginx, organizados por dominio.
• logs/php/: registros de PHP-FPM (php-fpm.log) y errores de ejecución PHP (errors.log). El archivo errors.log almacena errores no capturados por el propio framework o aplicación.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: errores, consultas lentas y otros logs para las distintas bases de datos.
• Otros logs de servicios: Python, Go, Java, Ruby, Rust, etc., se organizan en sus respectivos subdirectorios.

Nota: Los archivos de registros, especialmente los de acceso y errores, pueden consumir mucho espacio en disco en proyectos activos. Se recomienda revisar y limpiar periódicamente los logs innecesarios para optimizar el uso de almacenamiento.

Directorio de paquetes de software (package)

/Applications/ServBay/package

En este directorio se almacenan e instalan todos los paquetes de software gestionados por ServBay. Cada paquete tiene su propio subdirectorio, típicamente organizado como nombre/versión_principal/versión_completa. Por ejemplo, una versión concreta de PHP puede estar en /Applications/ServBay/package/php/8.3/8.3.7.

El panel de control de ServBay permite instalar, eliminar o cambiar versiones de los diferentes paquetes de manera sencilla.

Para liberar espacio, puedes eliminar manualmente subdirectorios de versiones antiguas que ya no utilizas, por ejemplo /Applications/ServBay/package/php/8.2/8.2.10.

Aviso importante: En cada carpeta de versión principal (por ejemplo /Applications/ServBay/package/php/8.3), existe un enlace simbólico llamado current apuntando a la subversión actualmente activa o más reciente. No borres ni modifiques estos enlaces simbólicos, de lo contrario ServBay podría perder referencia a los ejecutables o librerías necesarias haciendo que los servicios no inicien.

Directorio de certificados SSL (ssl)

/Applications/ServBay/ssl

Aquí se almacenan archivos relacionados con certificados SSL/TLS, incluyendo:

• Certificados SSL generados automáticamente para tus sitios locales usando el protocolo ACME (usualmente en ssl/caddy o ssl/acme, dependiendo del servidor web).
• Certificados raíz y públicos generados por ServBay para desarrollo local HTTPS (ssl/private y ssl/public). Instala estos certificados CA en tu sistema de confianza para evitar advertencias en el navegador al usar HTTPS en sitios locales.

Directorio de backups (backup)

/Applications/ServBay/backup

Esta carpeta almacena los archivos generados por el sistema de backup automático de ServBay. El respaldo abarca datos y configuraciones críticas de desarrollo, como:

• backup/config: respaldo de configuraciones principales y de paquetes.
• backup/databases: respaldo de los datos de MariaDB, MySQL, PostgreSQL, MongoDB, etc.
• backup/ssl: respaldo de certificados SSL.
• backup/websites: respaldo de tus archivos de sitios web almacenados en /Applications/ServBay/www.

Revisa periódicamente los contenidos de este directorio y considera transferir copias de respaldo a dispositivos externos para mayor seguridad.

Directorio de archivos temporales (tmp)

/Applications/ServBay/tmp

Este directorio almacena archivos temporales generados por los servicios, destacando los archivos .pid y archivos socket.

• Archivos .pid: registran el ID de proceso de los servicios en ejecución.
• Archivos socket: por ejemplo, php-cgi.sock, mysql.sock, pgsql.sock, etc. Permiten a los programas locales comunicarse con servicios como php-fpm o bases de datos mediante Unix Domain Sockets. Esta vía de comunicación suele ser más eficiente, rápida y con menor latencia que las conexiones TCP, especialmente para procesos locales.

Componentes comunes y bibliotecas de desarrollo (package/common)

/Applications/ServBay/package/common

Aquí se encuentran componentes compartidos y bibliotecas esenciales para los distintos paquetes instalados en ServBay (como *.dylib) y, opcionalmente, bibliotecas para desarrollo.

Si has instalado ServBay Development Library (un paquete opcional para quienes compilan extensiones desde código), también encontrarás los subdirectorios include (archivos de cabecera) y lib (librerías estáticas *.a y de enlace *.la). Estos archivos son necesarios al compilar extensiones de PHP u otro software que requiera las librerías de ServBay.

Aviso importante: No elimines manualmente archivos *.dylib del directorio package/common/lib, ya que son indispensables para el correcto funcionamiento de los servicios integrados. Su eliminación provocará errores de ejecución por falta de dependencias.

Resumen

La estructura de directorios de ServBay separa de forma clara los paquetes de software, la configuración, los datos, los registros y los archivos de los sitios web, inspirándose en la organización típica de los sistemas de archivos Unix. Esto permite a los desarrolladores gestionar su entorno local de forma intuitiva y eficaz. Familiarizarse con estos directorios potenciará su productividad y comodidad en el desarrollo web con ServBay. Realiza copias de seguridad periódicas, especialmente de las carpetas data y db, para asegurar la integridad y continuidad tu trabajo de desarrollo.