Explicação Detalhada da Estrutura de Diretórios do ServBay

O ServBay é um ambiente local de desenvolvimento Web projetado especialmente para o macOS, com uma estrutura de diretórios simples e bem organizada. Se você já conhece sistemas Linux/Unix, perceberá muitas semelhanças entre o esquema de arquivos do ServBay e a disposição tradicional dos sistemas de arquivos Unix, facilitando a localização e gestão dos arquivos para desenvolvedores.

Entender a estrutura de diretórios do ServBay é fundamental para otimizar o desenvolvimento local, configurar o ambiente, solucionar problemas e realizar backups seguros dos seus dados. Neste artigo, detalharemos os principais diretórios do ServBay e suas respectivas funções.

A seguir, um exemplo da estrutura típica de instalação do ServBay:

ServBay
|____backup                 # Diretório para arquivos de backup
| |____config               # Backup das configurações
| |____databases            # Backup dos bancos de dados
| |____ssl                  # Backup de certificados SSL
| |____websites             # Backup dos arquivos dos sites
|____bin                    # Diretório de executáveis do usuário (link simbólico para package/bin)
|____data                   # Diretório de dados internos do ServBay
| |____servbay              # Configurações centrais e dados do ServBay
|____db                     # Diretório de armazenamento dos bancos de dados
| |____mariadb              # Dados do MariaDB
| |____mongodb              # Dados do MongoDB
| |____mysql                # Dados do MySQL
| |____postgresql           # Dados do PostgreSQL
| |____redis                # Dados do Redis
|____etc                    # Diretório para arquivos de configuração (link simbólico para package/etc)
|____logs                   # Diretório de arquivos de log (link simbólico para package/var/log)
|____package                # Diretório de instalação dos pacotes de software
| |____bin                  # Executáveis dos pacotes de software
| |____common               # Bibliotecas compartilhadas e bibliotecas de desenvolvimento
| | |____imap-uw
| | |____include            # Arquivos de header (ServBay Development Library)
| | |____lib                # Bibliotecas compartilhadas e estáticas (ServBay Development Library)
| | |____libexec
| | |____openssl
| | |____share
| |____etc                  # Local real dos arquivos de configuração dos pacotes
| | |____caddy
| | |____dnsmasq
| | |____mariadb
| | |____mongodb
| | |____mysql
| | |____nginx
| | |____openldap
| | |____php
| | |____postgresql
| | |____redis
| | |____... (configurações de outros pacotes como Python, Go, Java, Ruby, Rust etc.)
| |____<package_name>       # Diretório principal de cada pacote
| | |____<major_version>   # Diretório da versão principal
| | | |____<full_version> # Diretório da versão completa (inclui o pacote em si)
| | | |____current         # Link simbólico para a versão mais recente/ativa
| | |____...
| |____sbin                 # Executáveis do sistema dos pacotes
| |____var                  # Dados variáveis dos pacotes (como o local real dos logs)
| | |____log                # Local real de armazenamento dos logs
| | |____run                # Arquivos de runtime (como arquivos .pid)
|____sbin                   # Diretório de executáveis do sistema (link simbólico para package/sbin)
|____script                 # Scripts de gerenciamento internos do ServBay
|____ssl                    # Diretório de certificados SSL
| |____acme                 # Certificados SSL obtidos via protocolo ACME
| |____caddy                # Certificados SSL gerados automaticamente pelo Caddy
| |____import               # Certificados SSL de terceiros importados pelo usuário
| |____private              # ServBay User CA
| |____public               # ServBay Public CA
|____tmp                    # Diretório para arquivos temporários e sockets
|____www                    # Diretório raiz dos sites
| |____servbay              # Diretório de site de exemplo

A seguir, detalhamos o propósito de cada diretório.

Diretório Principal do ServBay

O diretório principal do ServBay, por padrão, encontra-se em /Applications/ServBay. Todos os pacotes, arquivos de configuração, dados, logs e afins do ServBay ficam centralizados nesse local.

Para garantir a segurança do ambiente de desenvolvimento e dos seus dados, recomenda-se fazer backup periódico desse diretório principal usando ferramentas como Time Machine ou outro sistema de backup abrangente do diretório /Applications/ServBay.

Diretório Raiz dos Sites (www)

Os arquivos dos sites ficam em /Applications/ServBay/www. É aqui que você deve colocar os arquivos de todos seus projetos e aplicações web locais.

Para manter o ambiente organizado e facilitar a gestão, recomenda-se criar uma subpasta separada para cada site/projeto individual ou virtual host (chamado de “site” no ServBay).

Por exemplo, se você criou os sites web.servbay.demo, api.servbay.demo e new.servbay.local, a disposição recomendada dos arquivos seria assim:

/Applications/ServBay/www
|____servbay.demo           # Todos os sites do domínio *.servbay.demo
| |____web               # Arquivos do site web.servbay.demo
| |____api               # Arquivos do site api.servbay.demo
|____servbay.local          # Todos os sites do domínio *.servbay.local
| |____new               # Arquivos do site new.servbay.local
|____myproject              # Outros projetos independentes, ex: myproject.local

Esse padrão facilita a separação de projetos e domínios, tornando a gestão do ambiente muito mais clara.

Diretório de Configurações (etc)

O diretório de configurações /Applications/ServBay/etc é um link simbólico para /Applications/ServBay/package/etc. É onde ficam os arquivos de configuração principais de todos os pacotes que o ServBay instala (PHP, MariaDB, Nginx, Caddy, etc.).

No uso diário, basta acessar ou editar arquivos diretamente no caminho /Applications/ServBay/etc. Após alterações na maioria das configurações, será necessário reiniciar o serviço relacionado para aplicar as modificações.

Veja exemplos de armazenamento de configurações para alguns pacotes comuns:

PHP (etc/php)

Os arquivos de configuração do PHP ficam organizados em duas camadas para distinguir as versões principais do PHP. Por exemplo, dentro de etc/php você encontrará pastas como 5.6, 7.4, 8.3, cada uma correspondente a uma versão principal. Estrutura típica:

php
|____5.6                    # Configuração do PHP 5.6
| |____conf.d               # Diretório para config. de extensões
| |____php.ini              # Arquivo principal de configuração do PHP
|____7.4                    # Configuração do PHP 7.4
| |____conf.d               # Diretório para config. de extensões
| |____php-fpm.d            # Diretório de configuração dos pools do PHP-FPM
| |____php-fpm.conf         # Configuração principal do PHP-FPM
| |____php.ini              # Arquivo principal de configuração do PHP
|____8.3                    # Configuração do PHP 8.3
| |____conf.d
| |____php-fpm.d
| |____php-fpm.conf
| |____php.ini
|____... (outras versões do PHP)

Cada diretório de versão inclui o php.ini (configuração principal), php-fpm.conf (configuração principal do FPM, se disponível), pear.conf e outros arquivos. Depois de modificar algum deles, use o painel de controle do ServBay ou o comando servbayctl para reiniciar o PHP-FPM dessa versão.

O diretório conf.d concentra as configurações de extensões, como xdebug.ini, opcache.ini, redis.ini etc. Alterar esses arquivos serve para ativar/desativar ou configurar extensões do PHP — lembre-se de reiniciar o PHP-FPM correspondente após a modificação.

Observação: O ServBay usa o mesmo diretório de configuração para todas as subversões de um mesmo PHP principal; por exemplo, tanto o PHP 8.3.3 quanto o 8.3.5 partilham os arquivos em etc/php/8.3.

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

Os diretórios de configuração dos bancos também são organizados por versão, como etc/mariadb/11.2. Neles você encontrará arquivos principais, como o my.cnf (MariaDB/MySQL) ou postgresql.conf (PostgreSQL). Lembre-se de reiniciar o banco correspondente após alterações. Da mesma forma, cada subversão partilha o mesmo diretório de configuração do respectivo major version.

Para redefinir a senha do usuário root nesses bancos, utilize os utilitários de linha de comando ou a funcionalidade específica do painel do ServBay, em vez de editar diretamente o arquivo de configuração.

Caddy (etc/caddy)

O arquivo de configuração do Caddy (Caddyfile) está em etc/caddy.

Atenção: O arquivo Caddyfile é gerado automaticamente pelo ServBay conforme as configurações de sites feitas via painel de controle. Não edite esse arquivo manualmente, pois suas alterações podem ser sobrescritas quando o ServBay gerar a configuração novamente. Para customizar a configuração de um site, edite pelas opções oferecidas no painel do ServBay.

Nginx (etc/nginx)

O arquivo principal de configuração do Nginx, nginx.conf, está em etc/nginx. Assim como o Caddy, o ServBay pode gerar ou incluir trechos de configuração automaticamente conforme os sites definidos. Caso precise editar manualmente, faça-o com cautela — geralmente é preferível usar o painel do ServBay.

dnsmasq (etc/dnsmasq)

O diretório inclui o dnsmasq.conf (configuração padrão) e o domains.conf (arquivos gerados automaticamente pelo ServBay para os domínios locais configurados).

Atenção: Ambos são mantidos automaticamente pelo ServBay para garantir o funcionamento correto da resolução de domínios locais. Não os edite manualmente, pois alterações podem tornar os sites locais inacessíveis.

Configurações de Outros Pacotes

Demais pacotes suportados pelo ServBay — Node.js, Python, Go, Java, Ruby, Rust etc. — caso utilizem arquivos de configuração globais ou de nível de serviço, também armazenam esses arquivos no subdiretório correspondente em etc, seguindo o padrão por versão.

Diretório de Dados Internos do ServBay (data/servbay)

/Applications/ServBay/data/servbay

Esse diretório guarda arquivos críticos de configuração, informações de status e preferências de usuário necessários para o funcionamento normal do próprio aplicativo ServBay — incluindo a interface de controle, gestão dos pacotes, sites e bancos de dados.

Atenção: Faça backup periódico desse diretório e não apague nem altere os arquivos manualmente, pois isso pode fazer com que o ServBay pare de funcionar corretamente ou perca configurações importantes.

Diretórios de Executáveis e Scripts (bin, sbin, script)

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

Todos os executáveis ficam organizados em bin e sbin, ambos links simbólicos para package/bin e package/sbin. Nesses diretórios estão as diversas ferramentas e runtimes de linguagem integrados ao ServBay.

Ao iniciar o ServBay, esses caminhos são automaticamente adicionados à variável de ambiente PATH do sistema, permitindo acesso fácil via terminal. Exemplos do que pode ser encontrado:

• Utilitários populares: curl, openssl, frpc etc.
• Runtimes de linguagem de várias versões: php (versão padrão), php-5.6, php-7.4, php-8.3, node (padrão), node-16, node-18, python3, go, java, ruby, rustc etc. Para usar uma versão específica de um runtime, basta chamar o executável com a versão desejada.
• Clientes de bancos: mysql, psql, mongosh, redis-cli etc.

O diretório script (/Applications/ServBay/script) inclui scripts internos para gerenciamento do sistema — por exemplo, iniciar/parar serviços, inicializar bancos de dados ou tarefas de manutenção. Apesar de poder executá-los diretamente, é preferível usar o comando servbayctl, mais amigável e que encapsula esses scripts.

Por exemplo, para iniciar o PHP 7.4 FPM, rode:

servbayctl start php 7.4

O utilitário servbayctl pode ser acessado em /Applications/ServBay/bin.

Diretório de Bancos de Dados (db)

/Applications/ServBay/db

Aqui ficam, organizados por sistema e versão, todos os bancos instalados pelo ServBay:

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

Cada grande versão de um banco utiliza o mesmo diretório de dados (ex: todos MariaDB 11.2.x usam /Applications/ServBay/db/mariadb/11.2).

Atenção: Este diretório guarda todos os dados dos bancos locais. Faça backup completo de /Applications/ServBay/db antes de qualquer ação crítica como atualizações ou migração de sistema. A funcionalidade de backup automático do ServBay também inclui esses dados.

Diretório de Logs (logs)

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

Todos os logs dos serviços são centralizados em /Applications/ServBay/logs, um link simbólico para /Applications/ServBay/package/var/log. Assim, você pode monitorar facilmente o status e erros dos serviços.

Os arquivos de log são subdivididos por serviço, por exemplo:

• logs/caddy/ ou logs/nginx/: logs de acesso e erro do Caddy ou Nginx, geralmente organizados por subdomínio.
• logs/php/: inclui logs do PHP-FPM (php-fpm.log) e logs de erro do PHP (errors.log). O errors.log registra erros fatais não capturados pelos frameworks/applications.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: logs de erro, slow query etc. de cada banco.
• Logs de outros serviços: Python, Go, Java, Ruby, Rust e outros armazenados em subdiretórios próprios.

Atenção: Logs de acesso e erro podem consumir muito espaço em disco, especialmente em projetos ativos. Recomenda-se checar e limpar periodicamente os logs desnecessários.

Diretório de Pacotes de Software (package)

/Applications/ServBay/package

Aqui ficam todos os pacotes de software instalados e gerenciados pelo ServBay. Cada pacote fica em seu próprio subdiretório, usando o esquema nome_pacote/versao_maior/versao_completa. Exemplo: o PHP pode ser instalado em /Applications/ServBay/package/php/8.3/8.3.7.

Você pode instalar, remover ou alternar versões facilmente pelo painel de controle do ServBay.

Após upgrade, para economizar espaço, apague manualmente diretórios de versões antigas que não forem mais necessários, como /Applications/ServBay/package/php/8.2/8.2.10.

Atenção: Cada diretório de versão maior geralmente traz um link simbólico chamado current para a versão ativa da série (exemplo: /Applications/ServBay/package/php/8.3/current aponta para a subpasta da versão mais recente). Nunca apague ou altere esses links manualmente, pois isso pode impedir o correto funcionamento do ServBay.

Diretório de Certificados SSL (ssl)

/Applications/ServBay/ssl

Este diretório contém os certificados SSL/TLS usados pelo ServBay:

• Certificados obtidos pelo protocolo ACME para seus sites locais (em ssl/caddy ou ssl/acme, dependendo do servidor web utilizado).
• Certificados raiz gerados pelo ServBay para desenvolvimento HTTPS local: CA do usuário (ssl/private) e CA pública (ssl/public). Instale esses certificados no sistema confiável para evitar avisos de HTTPS no navegador dos seus sites locais.

Diretório de Backups (backup)

/Applications/ServBay/backup

Aqui ficam os arquivos produzidos pelo mecanismo de backup automático do ServBay, incluindo:

• backup/config: backup das configurações centrais e configurações dos pacotes.
• backup/databases: backup das bases de dados MariaDB, MySQL, PostgreSQL, MongoDB etc.
• backup/ssl: backup dos certificados SSL.
• backup/websites: backup dos arquivos dos projetos em /Applications/ServBay/www.

Cheque periodicamente esse diretório e, se possível, transfira os backups para um armazenamento externo para garantir maior resiliência dos seus dados.

Diretório de Arquivos Temporários (tmp)

/Applications/ServBay/tmp

Aqui estão os arquivos temporários gerados pelos serviços, como arquivos .pid e sockets de comunicação.

• Arquivos .pid: registram o PID (identidade dos processos) dos serviços em execução.
• Arquivos de socket: exemplos incluem php-cgi.sock, mysql.sock, pgsql.sock, que permitem comunicação eficiente (via Unix Socket) entre processos locais, geralmente com performance e latência melhores que o acesso via porta TCP.

Componentes Compartilhados e Bibliotecas de Desenvolvimento (package/common)

/Applications/ServBay/package/common

Aqui ficam os componentes e bibliotecas compartilhadas necessárias para os pacotes do ServBay, como arquivos *.dylib e, se instalado o ServBay Development Library (opcional), as pastas include (headers) e lib (bibliotecas estáticas *.a e arquivos de link *.la). Essas bibliotecas são essenciais especialmente para compilar extensões do PHP ou outras dependências a partir do código-fonte.

Atenção: Não apague manualmente arquivos do diretório package/common/lib — especialmente os *.dylib —, pois são essenciais para o funcionamento dos softwares integrados. Deletá-los pode causar falhas por dependências ausentes.

Resumo

A estrutura de diretórios do ServBay separa pacotes, configurações, dados, logs e arquivos dos sites de modo claro e aderente aos padrões Unix. Isso facilita muito a administração do ambiente local de desenvolvimento para Web. Familiarizar-se com cada diretório aumentará sua produtividade, segurança e agilidade. Faça backups frequentes dos diretórios críticos — em especial data e db — para proteger seu trabalho contra perdas.