Pular para o conteúdo principal

Setup e instalação

Guia completo. O README é o resumo. Última atualização: 16/09/2026.

1. O que você precisa​

ItemVersão / nota
Gitclone deste repositório
PHP8.1+ local; Docker usa 8.3 com mysqli, pdo_mysql, gd, zip, mbstring
Composer2.x
Node.js20+ (somente para npm run build:css)
MySQL / MariaDB8 / 10.11+, utf8mb4_unicode_ci
Docker Desktopopcional, mas é o caminho suportado de runtime

O document root é a raiz do repo, não existe pasta public/ de app.

2. Variáveis de ambiente​

copy .env.example .env     # Windows
cp .env.example .env       # Unix

Obrigatórias para o processo subir de verdade:

  • DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE
  • APP_URL (e-mails, reset de senha, CLI)
  • MOVINGPAY_PROD_TOKEN e MOVINGPAY_PROD_CUSTOMER_ID (o loader exige)

Fortemente recomendadas em qualquer ambiente com gente real:

  • MOVINGPAY_HML_* se for usar homologação
  • SMTP_* (recuperação de senha)
  • AUTENTIQUE_* (módulo documentos)
  • GOOGLE_DRIVE_* (arquivos)
  • OPENAI_API_KEY (resumo de tarefas)
  • PAYUP_* quando a integração estiver ligada
  • TRUST_PROXY=1 atrás de TLS termination
  • SESSION_SECURE=1 em HTTPS

O loader (backend/config/env.php) lê .env ou env.txt (fallback para painel de hosting que bloqueia arquivo oculto). Variáveis já exportadas no processo não são sobrescritas.

Catálogo comentado: .env.example.

3. Banco​

Crie o schema vazio:

CREATE DATABASE amplia CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'amplia_user'@'%' IDENTIFIED BY 'troque-esta-senha';
GRANT ALL ON amplia.* TO 'amplia_user'@'%';
FLUSH PRIVILEGES;

Não há runner de migration nem tabela schema_migrations. Cada arquivo em database/migrations/ é um script idempotente (CREATE TABLE IF NOT EXISTS e checagem em information_schema). Aplique em ordem cronológica:

20260727_backend_schema_baseline.php
20260727_backend_security_hardening.php
20260727_super_admin_system_scope.php
20260728_permissions_catalog_metadata.php
20260728_white_label_security_hardening.php
20260728_seed_bandeiras_base.php
20260728_comercial_leads_module.php
20260728_assinaturas_module.php
20260730_tarefas_module.php
20260805_setores_usuario.php
20260807_user_ec_password_resets.sql
20260814_permissions_canonical_en.php
20260814_permissions_drop_legacy_aliases.php
20260814_user_setores.php
20260815_propostas_user_id.php
20260817_empresas_module.php
20260817_permissions_prune_redundant.php
20260821_estabelecimentos_cadastro_campos.php
20260821_estabelecimentos_status_compliance.php
20260821_taxas_padrao_g8pay_ec.php
20260824_estabelecimentos_documentos.php
20260824_estabelecimentos_kyc.php
20260827_user_taxas_antecipacao.php
20260903_google_drive_storage.php
20260903_usuarios_documentos.php
20260903_estabelecimentos_porte.php
20260907_estabelecimentos_status_pipeline.php
20260907_rename_entrepay_para_adquirente.php
20260907_taxa_cash_in.php
20260908_permissions_dedupe_unique.php
20260910_planos_id_autoincrement.php

Arquivos .sql avulsos (create_logs_troca_representante.sql, 20260805_current_schema_baseline.sql) aplicam-se com o cliente MySQL, não com php. O baseline SQL de 05/08 é snapshot; prefira a cadeia PHP se estiver subindo um banco novo a partir do zero depois do baseline PHP de 27/07.

php database/migrations/20260727_backend_schema_baseline.php
# ... demais .php na ordem acima
php tools/seed_permissions_and_assign_admin.php admin@seudominio.com

O seed cria/atribui o catálogo de flags ao e-mail informado. A senha inicial do admin deve ser definida no próprio script ou no fluxo de reset — não deixe senha padrão em produção.

4. Dependências de aplicação​

composer install
npm install
npm run build:css

vendor/ costuma ir no artefato de deploy (a imagem Docker já instala --no-dev). CSS compilado cai em assets/css/app.css.

5. Docker​

docker compose up --build -d
curl -s http://localhost:8080/backend/api/health.php

O entrypoint.sh:

  1. cria dirs de sessão, log e upload;
  2. materializa /var/www/html/.env a partir das env do processo que existirem no .env.example;
  3. avisa se DB_* estiver faltando;
  4. opcionalmente escreve o JSON da service account em backend/secrets/;
  5. sobe php-fpm e nginx (daemon off).

nginx bloqueia /.env, vendor/, database/, tools/, docs/, backend/src, backend/config, backend/logs.

Banco não está no compose: aponte DB_HOST para o host (host.docker.internal no Desktop) ou para o MySQL da rede.

Credencial Drive: ou GOOGLE_DRIVE_SERVICE_ACCOUNT_JSON (string), ou arquivo existente antes do compose up (o volume bind falha se o path não existe).

6. Sem Docker (Laragon / Apache)​

  1. Document root = pasta do repo.
  2. PHP 8.1+ com as mesmas extensões.
  3. vhost com AllowOverride se for usar .htaccess.
  4. APP_URL igual ao vhost.
  5. Permissão de escrita em backend/logs, backend/storage/sessions, uploads.

7. Smoke test​

  1. GET /backend/api/health.php → "Env e banco OK".
  2. Abrir / → tela de login.
  3. Login com o usuário seedado.
  4. Menu lateral carrega grupos conforme flags.
  5. GET /backend/api/auth/permissoes.php (logado) devolve lista + hash.

Se o health responder 503, leia db_error no JSON e docker compose logs app.

8. Infra externa no dia a dia​

DependênciaSem ela
MovingpayDashboard/transações/planos remotos falham; cadastro local ainda roda
AutentiqueMódulo documentos não envia/assina
Google DriveUpload de mídia de usuário falha; health em storage/drive-health.php
OpenAIBotão de resumo de tarefa retorna erro de config
SMTPForgot password não entrega e-mail

Integrações não bloqueiam o boot do PHP — falham no endpoint que as chama.