manoel freitas
1e215ac3d2
Origin e deploy passam a documentar git.hellomanoel.com; GitHub/GHCR ficam como legado/backup. Co-authored-by: Cursor <cursoragent@cursor.com>
148 lines
4.8 KiB
Markdown
148 lines
4.8 KiB
Markdown
# Amare Site
|
|
|
|
Aplicação Laravel 13 para assessoria de eventos (Fase 0 — Fundação).
|
|
|
|
## Requisitos
|
|
|
|
- PHP 8.4 com extensões `pdo_pgsql`, `intl`, `mbstring`, `zip`, `sodium` (canônico do `Dockerfile` e do CI; `composer.json` aceita `^8.3`)
|
|
- Composer 2.x
|
|
- Node.js 22+ e npm
|
|
- Docker e Docker Compose
|
|
|
|
## Setup local
|
|
|
|
1. Copie o ambiente:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
```
|
|
|
|
2. Suba o PostgreSQL (requer o `.env` do passo 1 — o serviço `app` referencia esse arquivo via `env_file`, e o Compose valida todo o `docker-compose.yml` mesmo ao subir só o `postgres`):
|
|
|
|
```bash
|
|
docker compose up -d postgres
|
|
```
|
|
|
|
3. Instale dependências e rode migrations:
|
|
|
|
```bash
|
|
composer install
|
|
npm install
|
|
php artisan migrate
|
|
```
|
|
|
|
4. (Opcional) Seed de desenvolvimento:
|
|
|
|
```bash
|
|
php artisan db:seed
|
|
```
|
|
|
|
5. Servidor de desenvolvimento:
|
|
|
|
```bash
|
|
php artisan serve
|
|
npm run dev
|
|
```
|
|
|
|
Painel interno: `/admin`
|
|
|
|
Healthcheck: `GET /up`
|
|
|
|
## Paridade local com produção (FrankenPHP via Docker Compose)
|
|
|
|
Além do fluxo host-side acima, `docker-compose.yml` tem um serviço `app` que builda a mesma imagem FrankenPHP usada em staging/produção (`Dockerfile`), útil para testar o comportamento real do container antes do deploy:
|
|
|
|
```bash
|
|
docker compose up -d # sobe postgres + app
|
|
php artisan migrate # rode migrations (o entrypoint do container não migra sozinho)
|
|
curl localhost:8000/up
|
|
```
|
|
|
|
O serviço `app` depende de `postgres` estar saudável (`depends_on: condition: service_healthy`) e sobrescreve `DB_HOST`/`DB_PORT` do `.env` para apontar para o serviço `postgres` pelo nome (o padrão `127.0.0.1` do `.env` só funciona para processos rodando no host). Não há job de CI dedicado a este smoke — o job `container` do CI já builda e healthcheca a mesma imagem.
|
|
|
|
## Variáveis principais
|
|
|
|
| Variável | Valor local |
|
|
|---|---|
|
|
| `APP_LOCALE` | `pt_BR` |
|
|
| `APP_TIMEZONE` | `America/Sao_Paulo` |
|
|
| `DB_CONNECTION` | `pgsql` |
|
|
| `SESSION_DRIVER` | `database` |
|
|
| `CACHE_STORE` | `database` |
|
|
| `QUEUE_CONNECTION` | `database` |
|
|
|
|
## Comandos de qualidade
|
|
|
|
```bash
|
|
composer quality # Pint + PHPStan + audit (composer + npm) + testes
|
|
composer test:unit # Unit + Architecture
|
|
composer test:feature # Feature + Livewire + Filament
|
|
composer test:browser # E2E browser
|
|
composer test # Todos os testes
|
|
```
|
|
|
|
## Banco de testes (PostgreSQL)
|
|
|
|
Feature tests usam PostgreSQL conforme `phpunit.xml` (`DB_DATABASE=amare_test`).
|
|
|
|
Crie o banco de teste uma vez (com PostgreSQL local via Docker Compose):
|
|
|
|
```bash
|
|
docker exec amare-postgres psql -U amare -d amare -c "CREATE DATABASE amare_test;"
|
|
```
|
|
|
|
## Armazenamento de mídia
|
|
|
|
Uploads de conteúdo usam o disco `public` em desenvolvimento. Crie o symlink antes de servir arquivos localmente:
|
|
|
|
```bash
|
|
php artisan storage:link
|
|
```
|
|
|
|
Em produção, configure `FILESYSTEM_DISK=r2` (Cloudflare R2). O disco legado `s3` continua suportado se necessário.
|
|
|
|
## Provedores de produção
|
|
|
|
Produção usa **Resend** (e-mail transacional) e **Cloudflare R2** (mídia pública via domínio customizado). Local e CI permanecem com defaults seguros (`MAIL_MAILER=log`/`array`, disco `public`).
|
|
|
|
### Checklist de variáveis (produção)
|
|
|
|
| Variável | Valor |
|
|
|---|---|
|
|
| `MAIL_MAILER` | `resend` |
|
|
| `RESEND_API_KEY` | API key Resend |
|
|
| `MAIL_FROM_ADDRESS` / `MAIL_FROM_NAME` | Remetente verificado no Resend |
|
|
| `FILESYSTEM_DISK` | `r2` |
|
|
| `R2_ACCESS_KEY_ID` | Access key do token R2 |
|
|
| `R2_SECRET_ACCESS_KEY` | Secret do token R2 |
|
|
| `R2_BUCKET` | Nome do bucket |
|
|
| `R2_ENDPOINT` | `https://<account_id>.r2.cloudflarestorage.com` |
|
|
| `R2_URL` | Domínio customizado público (ex.: `https://media.example.com`) |
|
|
|
|
Infra manual (fora do app): criar bucket R2, token API, mapear domínio customizado ao bucket, criar API key Resend e verificar domínio de envio.
|
|
|
|
## Credenciais de desenvolvimento
|
|
|
|
Após `php artisan db:seed`:
|
|
|
|
| Papel | E-mail | Senha |
|
|
|---|---|---|
|
|
| Admin | `admin@amare.local` | `password` |
|
|
|
|
**Somente para ambiente local.** Nunca usar em produção.
|
|
|
|
## Documentação normativa
|
|
|
|
- [SPEC.md](SPEC.md) — especificação do produto
|
|
- [docs/adr/](docs/adr/) — ADRs aceitas
|
|
- [docs/conventions/php-strict-types.md](docs/conventions/php-strict-types.md) — convenção de strict types
|
|
- [docs/operations/atualizacao-de-conteudo.md](docs/operations/atualizacao-de-conteudo.md) — runbook de atualização de conteúdo do site pelo painel admin
|
|
- [docs/deployment/dokploy.md](docs/deployment/dokploy.md) — deploy staging/produção no Dokploy + registry Gitea
|
|
|
|
## Deploy (Dokploy)
|
|
|
|
Staging publica automaticamente após CI verde em `main` (imagem no registry Gitea por SHA + alias `:staging`). Produção promove a **mesma digest** com workflow manual `Promote production` (sem rebuild).
|
|
|
|
Ver runbook completo: [docs/deployment/dokploy.md](docs/deployment/dokploy.md).
|