Manoel Freitas
7f4ea01f4b
Publish immutable FrankenPHP images to GHCR, auto-deploy staging after CI, and promote the same digest to production with smoke, backup, and rollback docs. Co-authored-by: Cursor <cursoragent@cursor.com>
135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
# Amare Site
|
|
|
|
Aplicação Laravel 13 para assessoria de eventos (Fase 0 — Fundação).
|
|
|
|
## Requisitos
|
|
|
|
- PHP 8.5+ com extensões `pdo_pgsql`, `intl`, `mbstring`, `zip`, `sodium`
|
|
- 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:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
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`
|
|
|
|
## Variáveis principais
|
|
|
|
| Variável | Valor local |
|
|
|---|---|
|
|
| `APP_LOCALE` | `pt_BR` |
|
|
| `APP_TIMEZONE` | `America/Fortaleza` |
|
|
| `DB_CONNECTION` | `pgsql` |
|
|
| `SESSION_DRIVER` | `database` |
|
|
| `CACHE_STORE` | `database` |
|
|
| `QUEUE_CONNECTION` | `database` |
|
|
|
|
## Comandos de qualidade
|
|
|
|
```bash
|
|
composer quality # Pint + PHPStan + audit + 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/deployment/dokploy.md](docs/deployment/dokploy.md) — deploy staging/produção no Dokploy + GHCR
|
|
|
|
## Deploy (Dokploy)
|
|
|
|
Staging publica automaticamente após CI verde em `main` (imagem GHCR 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).
|