{
  "id": "primeiros-passos",
  "title": "Primeiros passos",
  "description": "Instalação do ambiente de desenvolvimento local do James com Laravel Sail.",
  "type": "guide",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "instalação",
    "desenvolvimento",
    "sail"
  ],
  "related": [
    "home",
    "autenticacao",
    "contribuicao",
    "deploy"
  ],
  "sourceRefs": [
    "https://github.com/james-suite/james/blob/master/compose.yaml",
    "https://github.com/james-suite/james/blob/master/composer.json",
    "https://github.com/james-suite/james/blob/master/package.json"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Pré-requisitos\n\nTenha [Docker](https://docs.docker.com/engine/install/) e Docker Compose, [Composer](https://getcomposer.org/) e [Node.js com npm](https://nodejs.org/) instalados. O ambiente local usa Laravel Sail para executar PHP, PostgreSQL e Mailpit.\n\n## Instalação\n\n1. Clone o [repositório do James](https://github.com/james-suite/james) e entre na pasta do projeto.\n2. Instale as dependências PHP com `composer install`.\n3. Copie `.env.example` para `.env`.\n4. Gere a chave da aplicação com `./vendor/bin/sail artisan key:generate`.\n5. Inicie os containers com `./vendor/bin/sail up -d`.\n6. Crie o link de storage com `./vendor/bin/sail artisan storage:link`.\n7. Execute as migrações e seeds com `./vendor/bin/sail artisan migrate --seed`.\n8. Instale as dependências do front-end com `./vendor/bin/sail npm install`.\n9. Inicie o Vite com `./vendor/bin/sail npm run dev` ou gere os assets com `npm run build`.\n\n### Variáveis de ambiente\n\nO `.env.example` já aponta o banco para o serviço Docker `pgsql` e o e-mail local para o Mailpit. Confira especialmente `APP_URL=http://localhost`, `MEDIA_DISK=private`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` e `NOTIFICATIONS_MAIL_ENABLED`. Os valores de Telegram ficam vazios por padrão no desenvolvimento.\n\n## Testes e rotina local\n\nO James usa Pest para testes de unidade e feature. Na primeira execução, crie o banco de testes quando necessário; depois use `./vendor/bin/sail test` ou `./vendor/bin/sail artisan test --compact`. Para uma execução direcionada, acrescente o nome do arquivo ou `--filter=Notification`.\n\nDurante os testes, `phpunit.xml` desativa os canais externos de Telegram e e-mail.\n\nO scheduler pode ser mantido em execução com `./vendor/bin/sail artisan schedule:work`; a fila pode ser atendida com `./vendor/bin/sail artisan queue:listen --tries=1 --timeout=0`. Os comandos financeiros também podem ser executados manualmente:\n\n```bash\n./vendor/bin/sail artisan finance:process-recurrences\n./vendor/bin/sail artisan finance:rollover-invoices\n./vendor/bin/sail artisan finance:rollover-transactions\n```\n\n## Serviços locais\n\n- A aplicação é exposta pela porta configurada em `APP_PORT`.\n- O PostgreSQL usa `FORWARD_DB_PORT` quando essa variável é definida.\n- A aplicação fica disponível em [http://localhost](http://localhost).\n- O Mailpit oferece SMTP e painel web em [http://localhost:8025](http://localhost:8025).\n- O Vite usa a porta `5173` por padrão.\n\n## Comandos úteis\n\nUm alias `sail` pode simplificar os comandos repetidos. No shell, ele pode apontar para `vendor/bin/sail`. Os comandos mais usados são `sail down`, `sail shell`, `sail bin pint` e `sail artisan pail`.\n\nConsulte [Autenticação](doc:autenticacao) depois do primeiro acesso e [Deploy](doc:deploy) para o ambiente de produção.",
  "sections": [
    {
      "id": "pre-requisitos",
      "level": 2,
      "title": "Pré-requisitos",
      "text": "Tenha [Docker](https://docs.docker.com/engine/install/) e Docker Compose, [Composer](https://getcomposer.org/) e [Node.js com npm](https://nodejs.org/) instalados. O ambiente local usa Laravel Sail para executar PHP, PostgreSQL e Mailpit.",
      "line": 1
    },
    {
      "id": "instalacao",
      "level": 2,
      "title": "Instalação",
      "text": "1. Clone o [repositório do James](https://github.com/james-suite/james) e entre na pasta do projeto. 2. Instale as dependências PHP com `composer install`. 3. Copie `.env.example` para `.env`. 4. Gere a chave da aplicação com `./vendor/bin/sail artisan key:generate`. 5. Inicie os containers com `./vendor/bin/sail up -d`. 6. Crie o link de storage com `./vendor/bin/sail artisan storage:link`. 7. Execute as migrações e seeds com `./vendor/bin/sail artisan migrate --seed`. 8. Instale as dependências do front-end com `./vendor/bin/sail npm install`. 9. Inicie o Vite com `./vendor/bin/sail npm run dev` ou gere os assets com `npm run build`.",
      "line": 5
    },
    {
      "id": "variaveis-de-ambiente",
      "level": 3,
      "title": "Variáveis de ambiente",
      "text": "O `.env.example` já aponta o banco para o serviço Docker `pgsql` e o e-mail local para o Mailpit. Confira especialmente `APP_URL=http://localhost`, `MEDIA_DISK=private`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` e `NOTIFICATIONS_MAIL_ENABLED`. Os valores de Telegram ficam vazios por padrão no desenvolvimento.",
      "line": 17
    },
    {
      "id": "testes-e-rotina-local",
      "level": 2,
      "title": "Testes e rotina local",
      "text": "O James usa Pest para testes de unidade e feature. Na primeira execução, crie o banco de testes quando necessário; depois use `./vendor/bin/sail test` ou `./vendor/bin/sail artisan test --compact`. Para uma execução direcionada, acrescente o nome do arquivo ou `--filter=Notification`.  Durante os testes, `phpunit.xml` desativa os canais externos de Telegram e e-mail.  O scheduler pode ser mantido em execução com `./vendor/bin/sail artisan schedule:work`; a fila pode ser atendida com `./vendor/bin/sail artisan queue:listen --tries=1 --timeout=0`. Os comandos financeiros também podem ser executados manualmente:",
      "line": 21
    },
    {
      "id": "servicos-locais",
      "level": 2,
      "title": "Serviços locais",
      "text": "- A aplicação é exposta pela porta configurada em `APP_PORT`. - O PostgreSQL usa `FORWARD_DB_PORT` quando essa variável é definida. - A aplicação fica disponível em [http://localhost](http://localhost). - O Mailpit oferece SMTP e painel web em [http://localhost:8025](http://localhost:8025). - O Vite usa a porta `5173` por padrão.",
      "line": 35
    },
    {
      "id": "comandos-uteis",
      "level": 2,
      "title": "Comandos úteis",
      "text": "Um alias `sail` pode simplificar os comandos repetidos. No shell, ele pode apontar para `vendor/bin/sail`. Os comandos mais usados são `sail down`, `sail shell`, `sail bin pint` e `sail artisan pail`.  Consulte [Autenticação](doc:autenticacao) depois do primeiro acesso e [Deploy](doc:deploy) para o ambiente de produção.",
      "line": 43
    }
  ],
  "sourcePath": "content/primeiros-passos.md",
  "visuals": [],
  "apiVersion": 1
}