# RULES.md — Regras de Desenvolvimento para AI Coder Este arquivo define as regras que todo agente de IA (Kilo, GPT, Claude, etc.) deve seguir ao desenvolver código neste projeto **SyspanelLamp**. --- ## 1. Autor e Licença - **Autor:** Marco Costa & Syspanel — [www.syspanel.com.br](https://www.syspanel.com.br) - **Data de criação:** 05/09/2026 - **Licença:** MIT Todo arquivo criado ou modificado **deve** conter o cabeçalho de licença MIT com a atribuição ao autor quando aplicável. --- ## 2. Estrutura de Diretórios ``` dockersyspanellamp/ ├── src/ │ ├── 2404/ │ │ ├── Dockerfile.mysql8 ← Imagem Docker MySQL 8.0 (Ubuntu 24.04) │ │ └── Dockerfile.mariadb ← Imagem Docker MariaDB (Ubuntu 24.04) │ ├── configs/ │ │ ├── apache/ │ │ │ ├── apache_default ← VirtualHost Apache │ │ │ └── apache_envvars.sh ← Variáveis de ambiente do Apache │ │ ├── mysql/ │ │ │ ├── my.cnf ← Configurações do MySQL/MariaDB │ │ │ └── init.sql ← Script de inicialização MySQL/MariaDB │ │ ├── php/ │ │ │ └── php.ini ← Configurações do PHP 8.3 │ │ └── scripts/ │ │ ├── entrypoint-mysql.sh ← Entrypoint MySQL 8.0 │ │ ├── entrypoint-mariadb.sh ← Entrypoint MariaDB │ │ └── entrypoint.sh ← Entrypoint genérico (auto-detecção) │ ├── README.md │ ├── LICENSE │ └── RULES.md │ ├── app/ ← Volume bind-mount do código da aplicação ├── mysql/ ← Volume bind-mount dos dados do MySQL/MariaDB ├── mysql-mysql8/ ← Volume bind-mount dos dados MySQL 8.0 ├── mysql-mariadb/ ← Volume bind-mount dos dados MariaDB ``` > **Nota:** Cada variante de banco tem seu próprio Dockerfile e entrypoint. A variável `DATABASE` é usada como build-arg e variável de ambiente para o entrypoint. Cada imagem já contém apenas o banco correspondente. > Todos os arquivos de configuração (Apache, MySQL/MariaDB, PHP e scripts) estão centralizados em `src/configs/`. --- ## 3. Regras do Dockerfile (todas as variantes) - **Base image:** Sempre usar `ubuntu:24.04`. - **PHP version:** Deve ser controlada por `ARG PHP_VERSION`. Nunca hardcodear. - **PHP source:** Ubuntu 24.04 (Noble) inclui PHP 8.3 nativamente. Não usar PPAs de terceiros. - **MySQL 8.0:** Usar repositório oficial da Oracle (`repo.mysql.com`), versão 8.0. - **MariaDB:** Usar repositório nativo do Ubuntu 24.04 (`mariadb-server`, `mariadb-client`). - **Root password DB:** Controlada por `ARG DB_ROOT_PASS`. - **MySQL data dir:** Deve ser limpo (`rm -rf /var/lib/mysql/*`) no final do Dockerfile para garantir que o entrypoint sempre detecta primeiro boot. - **PHPMyAdmin:** Usar versão 5.2.1 oficial do phpmyadmin.net. - **Adminer:** Usar versão 6.0.1 oficial do adminer.org (GitHub releases). - **Nunca** incluir dados sensíveis hardcoded (senhas, chaves de API). - O `CMD` final sempre deve ser `apache2ctl -D FOREGROUND`. - Os Dockerfiles devem ser mantidos **idênticos** exceto pela seção de instalação do banco de dados, entrypoint e arquivos de configuração copiados. --- ## 4. Regras do Apache - **DocumentRoot:** `/var/www/html/public` - **AllowOverride All:** Sempre habilitado para funcionar com `.htaccess` (WordPress, Laravel, etc.) - **Alias /phpmyadmin:** Aponta para `/var/www/phpmyadmin` - **Alias /adminer:** Aponta para `/var/www/adminer` - Módulos obrigatórios habilitados: `rewrite`, `headers`, `php8.3` --- ## 5. Regras do MySQL / MariaDB - **Porta:** 3306 - **Charset padrão:** `utf8mb4` com collation `utf8mb4_general_ci` - **Socket:** `/var/run/mysqld/mysqld.sock` - **Diretório de dados:** `/var/lib/mysql` - **Detecção de primeiro boot:** Verificar se `/var/lib/mysql/mysql/system` existe antes de inicializar. - **Init script:** `/docker-entrypoint-initdb.d/init.sql` — executado apenas na primeira inicialização - Bancos criados automaticamente: `app`, `wordpress`, `laravel` - Usuários criados automaticamente: `app`, `wordpress`, `laravel` --- ## 6. Regras do Entrypoint ### Comportamento Geral - O entrypoint deve iniciar o banco de dados antes do Apache. - Deve aguardar o banco ficar disponível antes de prosseguir. - Deve suportar a variável `DATABASE` para especificar o tipo de banco (`mysql8` ou `mariadb`). - Se `DATABASE` não for fornecida, deve detectar automaticamente pelo diretório de dados. - Deve definir a senha do root no primeiro boot. - Deve executar o script `init.sql` apenas no primeiro boot. - Deve iniciar o Redis (`redis-server --daemonize yes`). - Deve criar `/app` e `/var/www/html/public` se não existirem. - Deve usar `exec "$@"` no final para passar o sinal correto para o Apache. ### MySQL 8.0 (`entrypoint-mysql.sh`) - Usar `mysqld --initialize-insecure` para inicializar o diretório de dados. - Usar `mysqladmin ping` para verificar disponibilidade. - Usar `ALTER USER 'root'@'localhost' IDENTIFIED BY` para definir a senha. ### MariaDB (`entrypoint-mariadb.sh`) - Usar `mariadb-install-db` para inicializar o diretório de dados. - Usar `mysqladmin ping` para verificar disponibilidade. - Usar `ALTER USER 'root'@'localhost' IDENTIFIED BY` para definir a senha. ### Entrypoint genérico (`entrypoint.sh`) - Suporta `mysql8` e `mariadb` como valores de `DATABASE`. --- ## 7. Regras dos Arquivos de Configuração - Arquivos de configuração (`.cnf`, `.conf`, `.sh`) **não devem** conter comentários desnecessários. - Usar tabulação ou 4 espaços para indentação — manter consistência com o estilo existente. - Não remover funcionalidades existentes sem justificativa. - Toda alteração deve ser compatível com versões anteriores sempre que possível. --- ## 8. Regras de Extensões PHP As seguintes extensões são **obrigatórias** e nunca devem ser removidas: ``` curl, mbstring, mysql, pdo, pdo_mysql, xml, zip, gd, imagick, intl, bcmath, soap, redis, opcache, readline, memcached ``` Adições de novas extensões são permitidas, desde que justificadas. --- ## 9. Regras de Portas Padrão | Porta Interna | Porta Externa Padrão | Serviço | |---|---|---| | 80 | 16900 | Apache / HTTP | | 3306 | 16901 | MySQL / MariaDB | | 6379 | 16902 | Redis | | 5050 | 16905 | Adminer | --- ## 10. Convenção de Commits (se usar Git) ``` (): Tipos: feat: nova funcionalidade fix: correção de bug docs: alteração em documentação build: alteração no Dockerfile / build system refactor: refatoração sem mudança de comportamento chore: tarefas de manutenção geral ``` Exemplo: `feat(docker): adiciona variante MariaDB` --- ## 11. Regras Gerais - Nunca usar `sudo` dentro do Dockerfile — rodar como root é o padrão no build. - Sempre usar `--no-install-recommends` no `apt-get install`. - Sempre limpar `apt cache` após instalação (`rm -rf /var/lib/apt/lists/*`). - Nunca expor senhas em logs ou mensagens de erro. - O fuso horário padrão é `America/Sao_Paulo`. - O idioma padrão é `en_US.UTF-8` com suporte a `pt_BR.UTF-8`.