185 lines
7.1 KiB
Markdown
Executable File
185 lines
7.1 KiB
Markdown
Executable File
# 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)
|
|
|
|
```
|
|
<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`.
|