{
  "id": "ambiente-de-desenvolvimento",
  "title": "Ambiente de desenvolvimento",
  "description": "Requisitos e comandos para preparar e executar o ambiente local de desenvolvimento do SGE.",
  "type": "development-guide",
  "status": "maintained",
  "visibility": "public",
  "tags": [
    "sge/desenvolvimento",
    "sge/operacao"
  ],
  "related": [
    "visao-geral",
    "pessoas-e-responsabilidades"
  ],
  "sourceRefs": [],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Para quem esta página serve\n\nEsta página é destinada a quem prepara o ambiente de desenvolvimento do SGE. Pessoas que apenas usam o sistema não precisam executar estes comandos: para entender o processo, devem começar em [Visão geral](doc:visao-geral) ou [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades).\n\nOs comandos abaixo criam uma cópia local do sistema para desenvolvimento e testes; eles não devem ser executados em um computador institucional de produção sem orientação da equipe técnica.\n\n## Requisitos\n\n- Docker Engine ou Docker Desktop com Docker Compose v2.\n- Git.\n- Composer e PHP 8.3+ apenas para o bootstrap local; a execução principal ocorre pelo Sail.\n\nO `compose.yaml` utiliza Laravel Sail com runtime PHP 8.5, PostgreSQL 18, Meilisearch e Mailpit.\n\n## Primeira configuração\n\n```bash\ncd /caminho/para/o/projeto/sge\ncomposer install\ncp .env.example .env\n./vendor/bin/sail up -d\n./vendor/bin/sail artisan key:generate\n./vendor/bin/sail artisan migrate\n./vendor/bin/sail npm install\n./vendor/bin/sail npm run build\n```\n\nSe o arquivo `.env` não existir, ele deve ser criado antes de iniciar os serviços. O Sail executa PHP, Artisan, Composer, NPM e os serviços definidos em `compose.yaml` dentro do ambiente Docker.\n\nPara facilitar os comandos, pode-se criar um alias na sessão do terminal:\n\n```bash\nalias sail='./vendor/bin/sail'\n```\n\nDepois disso, `sail artisan ...` equivale a `./vendor/bin/sail artisan ...`.\n\n## Comandos úteis\n\n```bash\n./vendor/bin/sail up -d\n./vendor/bin/sail down\n./vendor/bin/sail logs -f laravel.test\n./vendor/bin/sail shell\n./vendor/bin/sail artisan migrate\n./vendor/bin/sail artisan test\n./vendor/bin/sail composer run lint:check\n./vendor/bin/sail composer run types:check\n./vendor/bin/sail composer run test\n./vendor/bin/sail npm run dev\n```\n\nPara o desenvolvimento contínuo, o projeto também possui o script Composer `dev`:\n\n```bash\n./vendor/bin/sail composer run dev\n```\n\n## Serviços locais\n\n| Serviço     | Endereço padrão         | Uso                                           |\n| ----------- | ----------------------- | --------------------------------------------- |\n| Aplicação   | `http://localhost`      | Interface web.                                |\n| Vite        | `http://localhost:5173` | Assets e hot reload.                          |\n| Mailpit     | `http://localhost:8025` | Visualização dos e-mails enviados localmente. |\n| Meilisearch | `http://localhost:7700` | Busca local.                                  |\n| PostgreSQL  | `localhost:5432`        | Banco local, conforme as variáveis do `.env`. |\n\nAs portas podem ser alteradas no `.env` por `APP_PORT`, `VITE_PORT`, `FORWARD_DB_PORT`, `FORWARD_MAILPIT_DASHBOARD_PORT` e `FORWARD_MEILISEARCH_PORT`.\n\n## Cuidados\n\n> [!danger] Segredos e dados reais\n> Nunca versionar `.env`, credenciais de provedores externos ou dados reais. Alterações de banco, fluxo ou regra devem atualizar também a documentação relacionada.\n\n- Nunca registrar `.env` ou credenciais de provedores externos no Git.\n- Não usar dados reais em testes locais.\n- Não executar `php artisan` ou `npm` no host quando a intenção for usar o ambiente do projeto; prefira o prefixo `./vendor/bin/sail`.\n- Para apagar volumes e dados locais, confirmar o alvo antes de usar comandos destrutivos do Docker.\n- Toda migration deve ser revisável e reversível quando possível.\n- Atualizar a documentação junto com alterações de fluxo ou banco.",
  "sections": [
    {
      "id": "para-quem-esta-pagina-serve",
      "level": 2,
      "title": "Para quem esta página serve",
      "text": "Esta página é destinada a quem prepara o ambiente de desenvolvimento do SGE. Pessoas que apenas usam o sistema não precisam executar estes comandos: para entender o processo, devem começar em [Visão geral](doc:visao-geral) ou [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades).  Os comandos abaixo criam uma cópia local do sistema para desenvolvimento e testes; eles não devem ser executados em um computador institucional de produção sem orientação da equipe técnica.",
      "line": 1
    },
    {
      "id": "requisitos",
      "level": 2,
      "title": "Requisitos",
      "text": "- Docker Engine ou Docker Desktop com Docker Compose v2. - Git. - Composer e PHP 8.3+ apenas para o bootstrap local; a execução principal ocorre pelo Sail.  O `compose.yaml` utiliza Laravel Sail com runtime PHP 8.5, PostgreSQL 18, Meilisearch e Mailpit.",
      "line": 7
    },
    {
      "id": "primeira-configuracao",
      "level": 2,
      "title": "Primeira configuração",
      "text": "Se o arquivo `.env` não existir, ele deve ser criado antes de iniciar os serviços. O Sail executa PHP, Artisan, Composer, NPM e os serviços definidos em `compose.yaml` dentro do ambiente Docker.  Para facilitar os comandos, pode-se criar um alias na sessão do terminal:   Depois disso, `sail artisan ...` equivale a `./vendor/bin/sail artisan ...`.",
      "line": 15
    },
    {
      "id": "comandos-uteis",
      "level": 2,
      "title": "Comandos úteis",
      "text": "Para o desenvolvimento contínuo, o projeto também possui o script Composer `dev`:",
      "line": 38
    },
    {
      "id": "servicos-locais",
      "level": 2,
      "title": "Serviços locais",
      "text": "| Serviço     | Endereço padrão         | Uso                                           | | ----------- | ----------------------- | --------------------------------------------- | | Aplicação   | `http://localhost`      | Interface web.                                | | Vite        | `http://localhost:5173` | Assets e hot reload.                          | | Mailpit     | `http://localhost:8025` | Visualização dos e-mails enviados localmente. | | Meilisearch | `http://localhost:7700` | Busca local.                                  | | PostgreSQL  | `localhost:5432`        | Banco local, conforme as variáveis do `.env`. |  As portas podem ser alteradas no `.env` por `APP_PORT`, `VITE_PORT`, `FORWARD_DB_PORT`, `FORWARD_MAILPIT_DASHBOARD_PORT` e `FORWARD_MEILISEARCH_PORT`.",
      "line": 59
    },
    {
      "id": "cuidados",
      "level": 2,
      "title": "Cuidados",
      "text": "> [!danger] Segredos e dados reais > Nunca versionar `.env`, credenciais de provedores externos ou dados reais. Alterações de banco, fluxo ou regra devem atualizar também a documentação relacionada.  - Nunca registrar `.env` ou credenciais de provedores externos no Git. - Não usar dados reais em testes locais. - Não executar `php artisan` ou `npm` no host quando a intenção for usar o ambiente do projeto; prefira o prefixo `./vendor/bin/sail`. - Para apagar volumes e dados locais, confirmar o alvo antes de usar comandos destrutivos do Docker. - Toda migration deve ser revisável e reversível quando possível. - Atualizar a documentação junto com alterações de fluxo ou banco.",
      "line": 71
    }
  ],
  "sourcePath": "content/ambiente-de-desenvolvimento.md",
  "visuals": [],
  "apiVersion": 1
}