SyspanelLamp/RULES.md

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
• 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
├── docs/         ← Documentos do projeto e dos containers
├── 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)

<tipo>(<escopo>): <descrição>

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.