Estrutura de Diretórios do ServBay: Guia Completo

Visão Geral

O ServBay é um ambiente local de desenvolvimento web compatível com macOS e Windows, projetado com uma estrutura de diretórios organizada e intuitiva. Se você já trabalhou com sistemas Linux/Unix, perceberá semelhanças na maneira que o ServBay distribui seus arquivos, facilitando o gerenciamento para desenvolvedores que já estão familiarizados com esses padrões.

Localização Padrão de Instalação do ServBay

O ServBay fica, por padrão, instalado nos seguintes caminhos:

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

Compreender a estrutura de diretórios do ServBay é fundamental para otimizar o desenvolvimento local, configurar o ambiente, solucionar problemas e realizar backups de dados. Este guia detalha os principais diretórios presentes na instalação do ServBay e suas respectivas finalidades.

A estrutura típica de instalação do ServBay é:

ServBay
|____backup                 # Diretório de arquivos de backup
| |____config               # Backup de configurações
| |____databases            # Backup de bancos de dados
| |____ssl                  # Backup de certificados SSL
| |____websites             # Backup dos arquivos dos sites
|____bin                    # Diretório de executáveis do usuário (link para package/bin)
|____data                   # Dados internos do ServBay
| |____servbay              # Configurações e dados centrais do ServBay
|____db                     # Diretório de armazenamento de bancos de dados
| |____mariadb              # Arquivos de dados do MariaDB
| |____mongodb              # Arquivos de dados do MongoDB
| |____mysql                # Arquivos de dados do MySQL
| |____postgresql           # Arquivos de dados do PostgreSQL
| |____redis                # Arquivos de dados do Redis
|____etc                    # Diretório de configurações (link para package/etc)
|____logs                   # Diretório de logs (link para package/var/log)
|____package                # Diretório de instalação dos pacotes de software
| |____bin                  # Executáveis dos pacotes
| |____common               # Bibliotecas comuns e de desenvolvimento
| | |____imap-uw
| | |____include            # Cabeçalhos (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
| | |____... (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 (com o pacote)
| | | |____current         # Link para a versão completa mais atual
| | |____...
| |____sbin                 # Executáveis do sistema dos pacotes
| |____var                  # Dados variáveis dos pacotes (como logs reais)
| | |____log                # Localização dos arquivos de log
| | |____run                # Arquivos de runtime (ex: arquivos .pid)
|____sbin                   # Diretório de executáveis do sistema (link para package/sbin)
|____script                 # Scripts de gerenciamento interno do ServBay
|____ssl                    # Diretório de certificados SSL
| |____acme                 # Certificados SSL já emitidos via protocolo ACME
| |____caddy                # Certificados SSL gerados automaticamente pelo Caddy
| |____import               # Certificados SSL de terceiros importados pelo usuário
| |____private              # CA de Usuário do ServBay
| |____public               # CA Pública do ServBay
|____tmp                    # Diretório de arquivos temporários e sockets
|____www                    # Raiz dos sites
| |____servbay              # Diretório de exemplo de site

A seguir, detalhamos a utilidade de cada diretório.

Diretório Principal do ServBay

A pasta principal do ServBay normalmente fica em /Applications/ServBay. Nela estão concentrados todos os pacotes, arquivos de configuração, dados, logs e outros componentes relevantes.

Para garantir a segurança do seu ambiente e dos seus dados, é recomendável fazer backups regulares deste diretório principal. Ferramentas como o Time Machine ou outros programas de backup podem ser utilizadas para salvar todo o conteúdo de /Applications/ServBay.

Diretório Raiz dos Sites (www)

Os arquivos dos seus projetos de sites ficam em /Applications/ServBay/www. Esse é o local para armazenar todos os projetos web em desenvolvimento.

Para uma organização mais limpa e fácil de gerenciar, é altamente recomendado criar uma subpasta para cada projeto ou site virtual (no ServBay, chamados de “websites”).

Por exemplo, supondo que você tenha os sites web.servbay.demo, api.servbay.demo e new.servbay.local, a estrutura sugerida seria:

/Applications/ServBay/www
|____servbay.demo           # Reúne todos os sites com domínio *.servbay.demo
| |____web               # Arquivos do site web.servbay.demo
| |____api               # Arquivos do site api.servbay.demo
|____servbay.local          # Reúne sites *.servbay.local
| |____new               # Arquivos do site new.servbay.local
|____myproject              # Outros projetos independentes, como myproject.local

Esta estrutura facilita a separação dos projetos e domínios, tornando a administração muito mais simples.

Diretório de Configurações (etc)

O diretório /Applications/ServBay/etc é, na prática, um link simbólico para /Applications/ServBay/package/etc. Este é o local central onde ficam os arquivos de configuração dos pacotes instalados (PHP, MariaDB, Nginx, Caddy, etc).

No dia a dia, basta acessar /Applications/ServBay/etc para visualizar ou editar configurações. Após modificar a maioria dos arquivos, você deverá reiniciar o serviço correspondente para aplicar as alterações.

Exemplos de localização dos arquivos de configuração dos principais pacotes:

PHP (etc/php)

A configuração do PHP é organizada em dois níveis, diferenciando grandes versões. Por exemplo, dentro de etc/php, há as pastas 5.6, 7.4, 8.3, cada uma referente a uma versão principal. Estrutura típica:

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

Cada versão tem seu próprio php.ini (configuração principal), php-fpm.conf (se suportar FPM), pear.conf, etc. Após editar esses arquivos, reinicie o processo PHP-FPM via painel do ServBay ou pelo comando servbayctl para aplicar as mudanças.

A pasta conf.d contém as configurações das extensões, como xdebug.ini, opcache.ini, redis.ini, etc. Edite esses arquivos para ativar, remover ou ajustar extensões PHP. Lembre-se de também reiniciar o PHP-FPM após alterações.

Atenção: O design do ServBay faz com que cada versão secundária do PHP, dentro da mesma versão principal, compartilhe os arquivos de configuração. Por exemplo, PHP 8.3.3 e 8.3.5 usam a mesma pasta etc/php/8.3.

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

Os bancos de dados seguem a mesma lógica, com diretórios específicos por versão principal, como etc/mariadb/11.2. Os arquivos de configuração principais, como my.cnf para MariaDB/MySQL e postgresql.conf para PostgreSQL, ficam nestas pastas. Depois de alterar configurações, é necessário reiniciar o respectivo serviço.

A redefinição da senha do usuário root normalmente não é feita editando arquivos de configuração, mas sim via ferramentas do banco ou pelo painel do ServBay.

Caddy (etc/caddy)

O Caddyfile, arquivo de configuração do Caddy, fica dentro de etc/caddy.

Importante: O ServBay gera o Caddyfile automaticamente com base nas configurações feitas no painel de controle. Não edite este arquivo manualmente!. Suas alterações podem ser sobrescritas na próxima geração automática. Para adicionar configurações personalizadas a um site, utilize o painel do ServBay.

Nginx (etc/nginx)

O arquivo principal de configuração do Nginx, nginx.conf, está em etc/nginx. Assim como no Caddy, o ServBay também gera ou inclui partes do arquivo automaticamente. Tenha cautela ao editar manualmente e prefira usar o painel para fazer ajustes de sites.

dnsmasq (etc/dnsmasq)

As configurações do dnsmasq incluem o dnsmasq.conf (arquivo padrão) e o domains.conf (gerado pelo ServBay conforme os domínios locais configurados).

Atenção: Ambos os arquivos são gerenciados automaticamente pelo ServBay para garantir o correto funcionamento da resolução de domínios locais. Não edite esses arquivos manualmente, pois isso pode impedir o acesso aos seus sites locais.

Configuração de Outros Pacotes

Pacotes como Node.js, Python, Go, Java, Ruby, Rust, etc., caso possuam arquivos de configuração globais ou de serviço, geralmente ficam organizados de forma semelhante em subpastas dentro do diretório etc.

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

/Applications/ServBay/data/servbay

Aqui ficam os arquivos fundamentais para o funcionamento do ServBay, como configurações centrais, estados de serviços e personalizações do usuário. Esses dados são essenciais para o painel de controle, gerenciamento de pacotes, sites e bancos de dados.

Importante: Mantenha backups deste diretório. Jamais exclua ou altere arquivos manualmente, pois há risco de o ServBay não iniciar ou perder configurações.

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

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

Os executáveis do ServBay ficam nos diretórios bin e sbin, ambos são links para package/bin e package/sbin. Neles estão inclusos ferramentas integradas e as runtimes das linguagens.

Esses diretórios são automaticamente incluídos no PATH do sistema quando o ServBay inicia, permitindo fácil acesso via terminal a comandos como:

• Ferramentas essenciais: curl, openssl, frpc, etc.
• Runtimes de várias versões: php (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 versões específicas, basta usar o comando correspondente.
• Clientes de banco de dados: mysql, psql, mongosh, redis-cli, etc.

A pasta script (/Applications/ServBay/script) contém scripts internos do sistema, usados para tarefas como iniciar/parar serviços, inicializar bancos de dados ou executar rotinas de manutenção. São essenciais para o funcionamento do ServBay, e apesar de poderem ser executados diretamente, o recomendado é usar o utilitário servbayctl, que oferece uma interface mais amigável.

Por exemplo, para iniciar o PHP-FPM da versão 7.4:

servbayctl start php 7.4

O comando servbayctl está disponível em /Applications/ServBay/bin.

Diretório de Bancos de Dados (db)

/Applications/ServBay/db

Aqui ficam os dados dos bancos instalados e utilizados pelo ServBay, organizados por tipo de software e versão principal. Por exemplo:

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

O ServBay faz com que cada versão principal de banco compartilhe o mesmo conjunto de arquivos, por exemplo, MariaDB 11.2.x utiliza /Applications/ServBay/db/mariadb/11.2.

Atenção: Este diretório contém todos os dados dos seus bancos locais. Antes de operações complexas (upgrade, migração etc.), sempre faça backups completos de /Applications/ServBay/db. O recurso de backup automático do ServBay também inclui os bancos.

Diretório de Logs (logs)

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

Todos os logs dos serviços integrados estão centralizados em /Applications/ServBay/logs, que é um link para /Applications/ServBay/package/var/log. Assim, é simples monitorar status, erros e atividades dos serviços.

Os arquivos são organizados por tipo de serviço:

• logs/caddy/ e logs/nginx/: Logs de acesso e erro do Caddy ou Nginx, geralmente por domínio.
• logs/php/: Logs do PHP-FPM (php-fpm.log) e log de erros do PHP (errors.log). O errors.log registra falhas críticas não tratadas pelo framework ou aplicação.
• logs/mariadb/, logs/mysql/, logs/postgresql/, logs/mongodb/, logs/redis/: Logs de erro, consultas lentas, etc., dos respectivos bancos.
• Logs de outros serviços: Python, Go, Java, Ruby, Rust e demais, guardados em subpastas específicas.

Atenção: Arquivos de log, principalmente logs de acesso e erro, podem ocupar bastante espaço, especialmente em projetos ativos. Recomenda-se revisar e limpar arquivos antigos regularmente para liberar espaço no disco.

Diretório dos Pacotes de Software (package)

/Applications/ServBay/package

Este é o diretório onde os pacotes instalados do ServBay são guardados e gerenciados. Cada pacote tem sua pasta própria, geralmente organizada em três níveis: nome/versão principal/versão completa — por exemplo, PHP instalado em /Applications/ServBay/package/php/8.3/8.3.7.

A interface do ServBay permite instalar, remover e alternar versões de pacotes de forma simples.

Pacotes antigos podem ser excluídos manualmente para liberar espaço, como /Applications/ServBay/package/php/8.2/8.2.10.

Importante: Na pasta de cada versão principal (ex: /Applications/ServBay/package/php/8.3), há um link chamado current apontando para o subdiretório da versão ativa/recente. Não remova ou altere manualmente o link current, pois isso pode impedir que o ServBay localize os executáveis e bibliotecas corretamente, levando a falhas ao iniciar serviços.

Diretório de Certificados SSL (ssl)

/Applications/ServBay/ssl

Aqui ficam todos os certificados SSL/TLS. Inclui:

• Certificados gerados automaticamente via protocolo ACME para os sites locais (normalmente em ssl/caddy ou ssl/acme, dependendo do servidor web em uso).
• Certificados raiz para desenvolvimento HTTPS local: ServBay User CA e ServBay Public CA, geralmente em ssl/private e ssl/public. Instale esses certificados no sistema para que o navegador confie nos sites locais do ServBay, evitando alertas HTTPS.

Diretório de Backup (backup)

/Applications/ServBay/backup

Este diretório é reservado para os arquivos gerados pelo backup automático do ServBay. O recurso cobre:

• backup/config: Backup das configurações centrais e dos pacotes.
• backup/databases: Backup dos bancos MariaDB, MySQL, PostgreSQL, MongoDB.
• backup/ssl: Backup dos certificados SSL.
• backup/websites: Backup dos projetos de sites guardados em /Applications/ServBay/www.

Avalie periodicamente se precisa transferir backups para dispositivos externos, como parte de uma política de recuperação de dados mais robusta.

Diretório de Arquivos Temporários (tmp)

/Applications/ServBay/tmp

Aqui ficam arquivos gerados dinamicamente pelos serviços na execução. Os mais comuns são arquivos .pid e sockets.

• Arquivos .pid: Guardam o ID do processo do serviço ativo.
• Sockets: Como php-cgi.sock, mysql.sock, pgsql.sock etc., permitem comunicação local entre aplicações e serviços via Unix Domain Socket. Isso geralmente traz maior desempenho e menor latência, além de ser ideal para processos que rodam na mesma máquina.

Componentes Comuns e Bibliotecas de Desenvolvimento (package/common)

/Applications/ServBay/package/common

Este diretório reúne todos os componentes compartilhados e bibliotecas utilizados pelos pacotes do ServBay, incluindo as bibliotecas dinâmicas (*.dylib) e opcionais para desenvolvimento.

Se você instalar o ServBay Development Library (pacote opcional para compilar extensões e dependências), haverá uma pasta include (arquivos de cabeçalho) e lib (bibliotecas estáticas *.a e *.la). Estes são úteis para quem precisa compilar extensões PHP ou outros softwares que dependem das bibliotecas próprias do ServBay.

Importante: Não exclua os arquivos *.dylib da pasta package/common/lib. Eles são essenciais para o funcionamento dos pacotes integrados e sua ausência pode causar erros graves na execução dos programas.

Resumo

A estrutura de diretórios do ServBay facilita a separação dos pacotes, configurações, dados, logs e arquivos de sites, adotando convenções de sistemas Unix. Isso oferece uma experiência de gerenciamento direta para desenvolvedores que trabalham com o ambiente local. Conhecer a função de cada pasta ajuda a maximizar a produtividade e organização do seu workflow. Lembre-se sempre de fazer backups regulares dos diretórios críticos, principalmente data e db, garantindo a integridade do seu ambiente de desenvolvimento.