# Instalação local e bloqueio do anfitrião

Diagnóstico de 25/09/2026: Windows ARM64 em **Parallels ARM Virtual Machine**, sem Docker, WSL não instalado, sessão sem privilégios administrativos e virtualização não exposta. `wsl --install --no-distribution` falhou. Não foi instalado SuiteCRM nem criado utilizador/OAuth. A [documentação Parallels](https://kb.parallels.com/en/129497) identifica a limitação de virtualização aninhada/WSL2 neste cenário.

## Caminho recomendado nesta máquina: Docker no macOS anfitrião

1. Instalar e abrir [Docker Desktop para Mac](https://docs.docker.com/desktop/setup/install/mac-install/) no macOS. Este terminal Windows não tem acesso ao motor ou terminal do macOS.
2. Copiar a pasta `deploy/suitecrm` para uma pasta local do Mac. Não copiar `.secrets` de outra instalação. Não executar a aplicação directamente numa pasta partilhada: o Compose já usa volumes nomeados para base e aplicação.
3. No Terminal do Mac, dentro da pasta copiada, executar `bash start-local.sh`.
4. Concluir o instalador interactivo com `docker compose -f compose.json exec --user www-data web php bin/console suitecrm:app:install`, seguindo o README. A password da base encontra-se em `.secrets/db_password`; introduzi-la apenas no instalador, sem publicar no chat. Definir uma conta administradora própria; a conta comercial pode continuar por configurar.

O script gera passwords apenas se ausentes, restringe permissões e preserva volumes. Build ARM, instalação e arranque ainda não foram testados neste anfitrião. O endereço loopback pertence ao Mac, não ao Windows convidado. A ligação Laravel no Windows requer posteriormente um endereço HTTPS acessível pela VM, certificado confiável e proxy configurado; não activar a integração apontando para HTTP ou desactivando TLS.

## Windows com virtualização suportada

Depois de Docker Desktop e motor Linux estarem disponíveis, executar a partir da raiz do projecto:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/suitecrm/start-local.ps1 -CheckOnly
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/suitecrm/start-local.ps1
```

O script não instala funcionalidades do Windows nem reinicia o computador. Não resolve a limitação de virtualização do Parallels ARM.

## Configuração e afinação após instalação

- Concluir URL HTTPS, proxy, cookies seguros, utilizador técnico e OAuth conforme README. Guardar credenciais apenas no backend.
- Executar `php artisan suitecrm:probe` depois de configurar `SUITECRM_ENABLED`, `SUITECRM_BASE_URL` (incluindo `/legacy` quando aplicável), `SUITECRM_CLIENT_ID` e `SUITECRM_CLIENT_SECRET`. O comando autentica e consulta metadados de Contacts; não escreve registos nem mostra tokens. Código de saída não zero indica falha.
- Configurar Messenger e Schedulers conforme README. Começar com um worker; medir duração, memória e backlog antes de aumentar concorrência.
- Manter limites iniciais de PHP em 512 MB, uploads de 20 MB e execução de 120 segundos. São valores de partida, não resultados de benchmark. Medir latência, CPU/RAM, consultas lentas e crescimento de volumes com dados fictícios antes de ajustar.
- Validar permissões com a conta técnica, campos de identificação externa, idempotência, falhas, reconciliação e restauro antes da migração comercial. O probe não substitui esses testes.

O envio da outbox, migração comercial, TLS real, reconciliação, instalação de extensões e testes de carga permanecem pendentes. Este arranque não instala IA nem conclui os restantes requisitos funcionais do portal.