First Commit
This commit is contained in:
marco
@@ -0,0 +1,184 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user