marco
3a50f0550e
Add documentation explaining the docs/ directory purpose for storing project and container-related documents like guides, configuration notes, and useful commands. Update RULES.md to include the new directory in the project structure listing.
186 lines
7.2 KiB
Markdown
Executable File
186 lines
7.2 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
|
|
├── 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`.
|