Instalação e Configuração - ime-usp-br/laravel_11_starter_kit GitHub Wiki

Instalação e Configuração

Esta seção detalha os passos necessários para instalar e configurar o Projeto Base USP em seu ambiente de desenvolvimento local.

Pré-requisitos

Antes de começar, certifique-se de que seu ambiente de desenvolvimento atende aos seguintes requisitos:

  • PHP >= 8.2
  • Composer (Gerenciador de Dependências PHP)
  • Node.js >= (Verificar versão no package.json ou documentação do Vite/Laravel 11, ex: >=18.0)
  • NPM (Gerenciador de Pacotes Node.js, geralmente vem com o Node.js)
  • Um Servidor de Banco de Dados suportado pelo Laravel (ex: MySQL, PostgreSQL, SQLite). Para desenvolvimento inicial, SQLite é uma opção prática.

Passos de Instalação

  1. Clonar o Repositório: Abra seu terminal e clone o repositório do projeto base para um diretório local. Substitua <url-do-repositorio> pela URL correta e nome-do-seu-projeto pelo nome desejado para a pasta do projeto.

    git clone <url-do-repositorio> nome-do-seu-projeto

  2. Navegar para o Diretório: Entre na pasta do projeto recém-clonado.

    cd nome-do-seu-projeto

  3. Instalar Dependências PHP: Utilize o Composer para instalar todas as bibliotecas PHP necessárias.

    composer install

  4. Instalar Dependências JavaScript: Utilize o NPM para instalar as dependências de frontend.

    npm install

  5. Copiar Arquivo de Ambiente: Crie seu arquivo de configuração de ambiente local (.env) copiando o arquivo de exemplo.

    cp .env.example .env

    Importante: O arquivo .env contém informações sensíveis e NÃO DEVE ser versionado no Git (ele já está no .gitignore).

Configuração do Ambiente (.env)

O arquivo .env é fundamental para o funcionamento da aplicação, pois define as configurações específicas do seu ambiente (local, desenvolvimento, produção). Abra o arquivo .env recém-criado em um editor de texto e ajuste as seguintes variáveis essenciais:

Configurações Gerais da Aplicação (APP_*)

  • APP_NAME: Nome da sua aplicação (ex: "Meu Sistema USP"). Será usado em títulos e emails.
  • APP_ENV: Ambiente da aplicação. Para desenvolvimento local, use local. Para produção, use production.
  • APP_KEY: Fundamental para segurança! Será gerada no próximo passo. Se estiver vazia, gere com php artisan key:generate.
  • APP_DEBUG: Defina como true para desenvolvimento (mostra erros detalhados) e obrigatoriamente false em produção.
  • APP_URL: A URL base completa da sua aplicação no seu ambiente (ex: http://meu-projeto.test, http://127.0.0.1:8000).

Configuração do Banco de Dados (DB_*)

  • DB_CONNECTION: O tipo de banco de dados. Opções comuns: mysql, pgsql, sqlite. Para desenvolvimento rápido, sqlite é uma boa opção.
  • Para mysql ou pgsql:
    • DB_HOST: Endereço do servidor de banco de dados (ex: 127.0.0.1).
    • DB_PORT: Porta do servidor (ex: 3306 para MySQL, 5432 para PostgreSQL).
    • DB_DATABASE: Nome do banco de dados que você criou para a aplicação.
    • DB_USERNAME: Nome de usuário para acesso ao banco.
    • DB_PASSWORD: Senha do usuário do banco.
  • Para sqlite:
    • Comente (#) ou remova as variáveis DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD.
    • DB_DATABASE: Defina o caminho absoluto para o arquivo do banco SQLite. Use a função database_path(): 
      DB_CONNECTION=sqlite
DB_DATABASE= # Comente ou remova esta linha se usar a próxima
# DB_DATABASE=/caminho/absoluto/para/database/database.sqlite # Alternativa
DB_DATABASE="${APP_BASE_PATH}/database/database.sqlite" # Mais comum
      Nota: O arquivo SQLite (database/database.sqlite) será criado automaticamente se não existir ao executar as migrações, desde que o diretório database exista e tenha permissão de escrita.

Configuração da Senha Única USP (SENHAUNICA_*)

Estas credenciais são obrigatórias para que o login via Senha Única funcione. Obtenha-as no portal de sistemas da USP.

  • SENHAUNICA_KEY: Sua chave de consumidor (Client Key). Ex: sua_key_aqui
  • SENHAUNICA_SECRET: Seu segredo de consumidor (Client Secret). Ex: seu_segredo_aqui
  • SENHAUNICA_CALLBACK_ID: O ID numérico da sua aplicação registrado no portal USP. Ex: 123
  • SENHAUNICA_CODIGO_UNIDADE: Código numérico da sua unidade/órgão na USP. Ex: 8
  • SENHAUNICA_ADMINS, SENHAUNICA_GERENTES, SENHAUNICA_USERS: (Opcional) Listas de Números USP (codpes), separados por vírgula, para atribuição automática de papéis/permissões pelo pacote uspdev/senhaunica-socialite. Deixe vazio se não usar. Ex: SENHAUNICA_ADMINS=11111,22222
  • SENHAUNICA_DROP_PERMISSIONS: (Opcional) Se true, remove permissões hierárquicas do usuário se ele não estiver mais nas listas _ADMINS/_GERENTES do .env. Padrão é false.
  • SENHAUNICA_DEV: Define o ambiente do servidor Senha Única.
    • no: Usa o servidor de produção da USP. Use este em produção!
    • local ou prod: (Verificar documentação uspdev/senhaunica-socialite) Pode ser usado para apontar para ambientes de desenvolvimento/homologação da USP.
    • URL (ex: http://127.0.0.1:3141/wsusuario/oauth): Usa um servidor Senha Única falso (como o uspdev/senhaunica-faker-laravel) para testes locais.
  • SENHAUNICA_DEBUG: Se true, salva a resposta JSON do OAuth em storage/app/debug/oauth/ para fins de depuração. Padrão é true (recomendado para dev, false para prod).

Configuração do Replicado USP (REPLICADO_*)

Necessárias para a funcionalidade de busca e criação de usuários USP pela área administrativa. Obtenha as credenciais de acesso ao banco Replicado da sua unidade/STI.

  • REPLICADO_HOST: Endereço do servidor Replicado.
  • REPLICADO_PORT: Porta do servidor Replicado.
  • REPLICADO_DATABASE: Nome do banco de dados Replicado.
  • REPLICADO_USERNAME: Nome de usuário para acesso ao Replicado.
  • REPLICADO_PASSWORD: Senha do usuário do Replicado.
  • REPLICADO_SYBASE: (Opcional) Defina como true (padrão) se o Replicado for Sybase, ou false se for MS SQL Server (pode afetar tratamento de encoding/espaços).

Outras Configurações

  • Email (MAIL_*): Configure como os emails serão enviados (ex: log para salvar em arquivo de log durante o desenvolvimento, smtp para usar um servidor SMTP).
    • Para smtp: MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION (ex: tls), MAIL_FROM_ADDRESS, MAIL_FROM_NAME.
  • Cache (CACHE_STORE): Driver de cache. file (padrão), database, redis, memcached, array (bom para testes).
  • Fila (QUEUE_CONNECTION): Como as tarefas em fila são processadas. sync (imediatamente, bom para dev/testes), database (usa tabela no DB), redis.

Ambiente de Teste (.env.testing)

Este arquivo é usado automaticamente ao executar php artisan test. Ele sobrescreve as configurações do .env principal para otimizar a execução dos testes automatizados. As configurações padrão são:

  • APP_ENV=testing
  • DB_CONNECTION=sqlite
  • DB_DATABASE=:memory: (Banco de dados SQLite em memória, rápido e volátil)
  • CACHE_STORE=array (Cache em memória, isolado)
  • SESSION_DRIVER=array (Sessão em memória, isolada)
  • QUEUE_CONNECTION=sync (Tarefas executadas imediatamente)
  • MAIL_MAILER=array (Emails capturados em memória para asserções)
  • BCRYPT_ROUNDS=4 (Hashing de senha mais rápido)
  • Credenciais SENHAUNICA_* e REPLICADO_* com valores dummy (testes não devem depender de serviços externos reais, use Mocks).

Não é necessário editar .env.testing a menos que você tenha requisitos de teste muito específicos.

Comandos Artisan Essenciais Pós-Instalação

Após configurar o .env, execute os seguintes comandos no terminal, na raiz do projeto:

  1. Gerar Chave da Aplicação: (Se ainda não foi gerada ou se o .env foi criado manualmente)

    php artisan key:generate

  2. Executar Migrações: Cria as tabelas do banco de dados (usuários, sessões, cache, filas, permissões, etc.).

    php artisan migrate

  3. Executar Seeders: Popula o banco com dados iniciais, como os papéis e permissões padrão.

    php artisan db:seed

    Nota: Se precisar rodar um seeder específico: php artisan db:seed --class=NomeDoSeeder

  4. Criar Link Simbólico de Armazenamento: Torna a pasta storage/app/public acessível publicamente via /storage. Necessário para exibir arquivos como avatares ou uploads públicos.

    php artisan storage:link

  5. (Opcional) Limpar Caches: Útil se você modificar arquivos de configuração ou rotas.

    php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

Servindo a Aplicação

Para iniciar o servidor de desenvolvimento local e o processo de compilação de assets:

  1. Iniciar o Servidor PHP:

    php artisan serve

    Isso geralmente disponibiliza a aplicação em http://127.0.0.1:8000.

  2. Iniciar o Vite (Desenvolvimento Frontend): Abra outro terminal na raiz do projeto e execute:

    npm run dev

    Isso compila os assets (CSS, JS) e ativa o hot module replacement (HMR) para atualizações instantâneas no navegador durante o desenvolvimento frontend.

Agora você deve conseguir acessar sua aplicação no endereço fornecido pelo php artisan serve.