Windows Server with IIS

Faca deployment do FoxIDs em Windows Server com Internet Information Services, IIS.

Esta e uma descricao de como fazer um deployment predefinido e iniciar sessao pela primeira vez.

Uma instalação FoxIDs é autónoma, tem poucas dependências externas e consegue obter um uptime muito elevado com pouco esforço. O FoxIDs e atualizado descarregando o ficheiro FoxIDs-x.x.x-win-x64.zip a partir da nova release e depois atualizando os ficheiros nos dois websites, sem substituir appsettings.json. As novas releases do FoxIDs sao backward compatible; consulte as release notes antes de atualizar.

E necessaria uma licenca valida para aceder as releases do FoxIDs, onde pode descarregar os ficheiros de deployment necessarios.

Pre-requisitos:

Tem um Windows Server, ou Windows 10/11, com Internet Information Services, IIS.
Tem conhecimentos basicos de Windows Server e IIS.

Este guia descreve como instalar o FoxIDs num unico servidor, mas pode dividir a instalacao por servidores diferentes.

Este deployment inclui:

Dois websites, um para o FoxIDs e outro para o FoxIDs Control, Admin Client e API.
Os dois websites sao expostos em dois domains ou sub-domains diferentes.
Uma base de dados NoSQL contendo todos os dados incluindo tenants, ambientes e utilizadores. Distribua MongoDB Community Edition ou PostgreSQL.
Com "Log": "Stdout", o FoxIDs escreve logs para stdout. IIS stdout file logging está desativado nos ficheiros web.config incluídos; ative-o temporariamente para troubleshooting ou use OpenSearch em produção.

Deployment

O deployment e executado pela ordem descrita.

Install database

Descarregue e instale o MongoDB Community Edition ou descarregue e instale o PostgreSQL.

MongoDB
Um deployment MongoDB self-managed e instalado por predefinicao com access control desativado. Considere configurar a autenticacao do MongoDB de acordo com a sua instalacao.
Endpoint predefinido, connection string, do MongoDB: mongodb://localhost:27017

Pode instalar o MongoDB Compass, GUI, com o MongoDB Community Edition ou descarregar e instalar a aplicacao de administracao MongoDB separadamente.

PostgreSQL
O PostgreSQL e distribuido por predefinicao com o utilizador postgres e uma password fornecida por si durante a instalacao.

Abra o pgAdmin e crie uma base de dados para o FoxIDs chamada FoxIDs

Endpoint predefinido, connection string, do PostgreSQL: Host=localhost;Username=postgres;Password=xxxx;Database=FoxIDs

Add two websites

Ative o ASP.NET Core hosting e adicione os dois websites FoxIDs ao IIS.

Adicione o ASP.NET Core Module, ANCM, para IIS

Instale o .NET Core Hosting Bundle installer (direct download) para adicionar o ASP.NET Core Module, ANCM, para IIS, que e necessario para executar aplicacoes ASP.NET Core, mesmo que os websites FoxIDs sejam self-contained.
Reinicie o IIS ou o servidor

Adicione o website FoxIDs:

Nome do site FoxIDs
Physical path, por exemplo C:\inetpub\FoxIDs
O domain binding http para o seu dominio, por exemplo http://id.my-domain.com
Altere a app service .NET CLR Version para No Managed Code

E adicione o website FoxIDs Control:

Nome do site FoxIDs.Control
Physical path, por exemplo C:\inetpub\FoxIDs.Control
O domain binding http para o seu dominio, por exemplo http://control.my-domain.com
Altere a app service .NET CLR Version para No Managed Code

Opcionalmente adicione os dois domains ao ficheiro hosts do servidor C:\Windows\System32\drivers\etc\hosts para permitir testes locais no servidor:
   127.0.0.1     id.my-domain.com
   127.0.0.1     control.my-domain.com

HTTP and HTTPS

O FoxIDs suporta HTTP e HTTPS, mas em producao deve usar sempre HTTPS.

Pode ignorar esta secao se pretender executar o FoxIDs em HTTP sem certificado.

Pode usar os seus proprios certificados ou fazer com que um certificado seja criado pelo Let's encrypt.

Use your own certificate(s)
Instale os seus proprios certificados no servidor e configure bindings https para os dois websites.

Windows Server with IIS - add the FoxIDs website

Certificate created by Let's encrypt
Crie e adicione certificado Let's encrypt aos dois websites com win-acme.

Descarregue o ficheiro win-acme.v2.x.x.x64.pluggable.zip a partir da ultima release do win-acme.

Extraia e coloque a pasta win-acme.v2.x.x.x.x64.pluggable num local permanente, por exemplo na drive C. O componente e depois registado para ser executado no Windows Task Scheduler.
Inicie um Command Prompt elevado em modo administrativo
Navegue para a pasta win-acme.v2.x.x.x.x64.pluggable
Execute wacs.exe
Clique em N
Selecione os websites FoxIDs e FoxIDs.Control, provavelmente escrevendo: 2, 3
Clique em A
Escolha o site FoxIDs como host principal
Concorde com os termos, clique em N e depois em Y
Adicione o seu email

Os dois websites passam agora a ter bindings https com o certificado criado pelo Let's encrypt e o certificado sera atualizado automaticamente de 3 em 3 meses, aproximadamente.

Xcopy deploy FoxIDs to websites

Descarregue o ficheiro FoxIDs-x.x.x-win-x64.zip a partir da release do FoxIDs e extraia o ficheiro ZIP. O ficheiro zip contem duas pastas, uma para o site FoxIDs e outra para o site FoxIDs Control.

Faca Xcopy da pasta FoxIDs do ficheiro zip para o physical path do website, por exemplo C:\inetpub\FoxIDs
E faca Xcopy da pasta FoxIDs.Control do ficheiro zip para o physical path do website, por exemplo C:\inetpub\FoxIDs.Control

Configure tanto o site FoxIDs como o site FoxIDs Control nos ficheiros appsettings.json, localizados, por exemplo, em C:\inetpub\FoxIDs\appsettings.json e C:\inetpub\FoxIDs.Control\appsettings.json

Defina o domain do site FoxIDs em FoxIDsEndpoint, por exemplo http://id.my-domain.com ou https://id.my-domain.com
Apenas no site FoxIDs Control. Defina o domain do site FoxIDs Control em FoxIDsControlEndpoint, por exemplo http://control.my-domain.com ou https://control.my-domain.com
Se o domain comecar por http://..., remova o comentario de "UseHttp": true,

Configure o acesso a base de dados, quer para MongoDB

"Options": {
    "Log": "Stdout",
    "DataStorage": "MongoDb",
    "KeyStorage": "None",
    "Cache": "MongoDb",
    "DataCache": "None"
},
"MongoDb": {
    "ConnectionString": "mongodb://localhost:27017"
},

ou para PostgreSql com a password do seu utilizador postgres

"Options": {
    "Log": "Stdout",
    "DataStorage": "PostgreSql",
    "KeyStorage": "None",
    "Cache": "PostgreSql",
    "DataCache": "None"
},
"PostgreSql": {
  "ConnectionString": "Host=localhost;Username=postgres;Password=xxxxxxxx;Database=FoxIDs"
},

Opcionalmente configure o envio de emails com SMTP.

Patching and update strategy

Atualizar o FoxIDs segue a mesma mecanica do deployment Xcopy, mas um pouco de estrutura adicional mantem o downtime baixo e fornece um caminho de rollback simples.

Plan the window - Reveja as release notes mais recentes, o FoxIDs e backward compatible, salvo indicacao em contrario nas release notes, e agende uma curta janela de manutencao. Se os dois sites estiverem por tras de um load balancer, drene o trafego de um no de cada vez.
Stage the binaries - Descarregue o mais recente FoxIDs-x.x.x-win-x64.zip, extraia-o para pastas temporarias como C:\temp\FoxIDs.new e C:\temp\FoxIDs.Control.new, e copie os seus appsettings*.json e web*.config existentes.
Snapshot the current install - Pare os dois sites IIS, ou os respetivos App Pools. Faca Xcopy ou renomeie as pastas live, por exemplo C:\inetpub\FoxIDs → C:\inetpub\FoxIDs.2025-11-11.bak. Faca o mesmo para o site Control. Um backup comprimido ou um snapshot de VM tambem funciona, mas copias rapidas de pastas sao muitas vezes suficientes.
Swap in the update - Faca Xcopy das pastas preparadas para os paths live, C:\inetpub\FoxIDs e C:\inetpub\FoxIDs.Control, e volte a verificar que as permissoes NTFS herdadas ainda incluem as identidades corretas dos App Pools. Inicie novamente os App Pools ou sites para aquecer as aplicacoes.
Verifique e monitorize - Abra o site Control, complete um round-trip de login e execute uma pesquisa rápida de tenant ou track. Se ativou IIS stdout file logging, observe a pasta de logs C:\inetpub\logs\LogFiles\foxids para detetar erros. Se usar OpenSearch, verifique logs e erros no OpenSearch.
Rollback if needed - Se algo se comportar mal, pare os sites, renomeie as pastas recentemente distribuidas para .failed, restaure as pastas .bak aos nomes originais e inicie novamente o IIS. Como o schema da base de dados e backward compatible, os binarios anteriores retomam imediatamente.

Repita o processo para cada release; em configuracoes multi-servidor atualize um servidor de cada vez para manter a disponibilidade do servico.

FoxIDs log files

Com "Log": "Stdout", o FoxIDs escreve logs para stdout. Os ficheiros web.config incluídos definem stdoutLogEnabled="false" e stdoutLogFile="\\?\%home%\LogFiles\stdout".

Os erros de arranque do IIS e os erros do processo da aplicação FoxIDs também são escritos no Windows Application event log e podem ser vistos no Event Viewer.

Se precisar de ficheiros de log durante troubleshooting de problemas de arranque ou runtime no IIS, ative temporariamente stdoutLogEnabled e defina stdoutLogFile para um path como C:\inetpub\logs\LogFiles\foxids\stdout nos ficheiros web.config dos dois websites.

Crie a pasta \foxids\ em C:\inetpub\logs\LogFiles\ e conceda aos dois IIS App Pools iis apppool\foxids e iis apppool\foxids.control acesso total à pasta \foxids\. Desative novamente IIS stdout file logging depois do troubleshooting.

Os logs contem erros, avisos, eventos e trace.

OpenSearch

Dependendo da carga, considere usar OpenSearch em producao em vez de ficheiros de log.

Descarregue OpenSearch ou descarregue-o a partir da download page.

Crie uma pasta num local permanente, por exemplo C:\opensearch na drive C. O OpenSearch e depois instalado para ser executado como Windows Service.
Mova o ficheiro descarregado opensearch-x.x.x-windows-x64.zip para a pasta C:\temp, ou outra pasta com nome curto, e extraia-o - os nomes dos ficheiros sao demasiado longos para serem extraidos na pasta de downloads predefinida
Mova os ficheiros extraidos para a pasta C:\opensearch
Inicie um Command Prompt elevado em modo administrativo
Navegue para a pasta C:\opensearch
Defina uma password de administrador, execute set OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
Inicie o servico, execute \.\opensearch-windows-install.bat
Inicie outro Command Prompt
Teste o OpenSearch, execute o pedido de teste curl.exe -X GET https://localhost:9200 -u "admin:<custom-admin-password>" --insecure
Teste os plugins do OpenSearch, execute o pedido de teste curl.exe -X GET https://localhost:9200/_cat/plugins?v -u "admin:<custom-admin-password>" --insecure
Volte ao Command Prompt do OpenSearch e pare o OpenSearch clicando em ctrl+c e depois em y
As definicoes encontram-se em C:\opensearch\config\opensearch.yml; reveja-as.
Navegue para a pasta C:\opensearch\bin no Command Prompt do OpenSearch
Execute opensearch-service.bat install para instalar o Windows Service do OpenSearch
Execute opensearch-service.bat manager para abrir as definicoes do Windows Service do OpenSearch
Defina Startup type: como Automatic e clique em OK
Execute opensearch-service.bat start para iniciar o Windows Service do OpenSearch

O OpenSearch e iniciado por predefinicao com um certificado self-signed. Pode configurar um domain e um certificado, mas neste guia o certificado self-signed e mantido e o FoxIDs e configurado para o aceitar.

Configure o OpenSearch tanto no site FoxIDs como no site FoxIDs Control nos ficheiros appsettings.json, localizados, por exemplo, em C:\inetpub\FoxIDs\appsettings.json e C:\inetpub\FoxIDs.Control\appsettings.json

"Options": {
    "Log": "OpenSearchAndStdoutErrors",
    //DB configuration...
},
"OpenSearch": {
    "Nodes": [ "https://admin:xxxxxxxx@localhost:9200" ],
    "LogLifetime": "Max180Days", 
    "AllowInsecureCertificates": true //Accept self-signed certificate
},

Secure connection strings

Em producao, recomenda-se usar connection strings com passwords para MongoDB, PostgreSQL e OpenSearch.

Nao guarde passwords em appsettings.json. Mantenha os valores nao secretos em appsettings.json e configure os secrets como environment variables no IIS, tanto para o site FoxIDs como para o site FoxIDs Control. As environment variables substituem os valores em appsettings.json.

Configure estas environment variables no IIS:

MongoDb__ConnectionString
PostgreSql__ConnectionString
OpenSearch__Nodes__0, primeiro no OpenSearch incluindo credenciais

Defina apenas as variaveis que usa.

Valores de exemplo:

MongoDb__ConnectionString=mongodb://foxids:<password>@localhost:27017
PostgreSql__ConnectionString=Host=localhost;Username=postgres;Password=<password>;Database=FoxIDs
OpenSearch__Nodes__0=https://admin:<password>@localhost:9200

Os valores sao guardados na configuracao do IIS, applicationHost.config, fora da web root. Restrinja o acesso aos ficheiros de configuracao do IIS apenas a administradores.

Para configurar as variaveis no IIS:

Abra IIS Manager.
Selecione o site, FoxIDs ou FoxIDs.Control.
Abra Configuration Editor.
Va a system.webServer/aspNetCore.
Adicione os valores em environmentVariables.
Repita para o segundo site e reinicie ambos os App Pools.

Abra o seu site FoxIDs Control, http://control.my-domain.com ou https://control.my-domain.com, num browser. Devera redirecionar para o site FoxIDs, onde inicia sessao com o utilizador admin predefinido admin@foxids.com e password FirstAccess!, sendo obrigatorio alterar a password no primeiro login.
Depois e redirecionado de volta para o site FoxIDs Control no tenant master. Pode adicionar mais utilizadores admin no tenant master.

Depois clique no tenant main e autentique-se novamente com o mesmo utilizador admin predefinido admin@foxids.com e password FirstAccess!, mais uma vez sendo obrigatorio alterar a password.

O utilizador admin predefinido e a password sao os mesmos tanto para o tenant master como para o tenant main, mas sao dois utilizadores diferentes.

Esta agora autenticado no tenant main e pode comecar a configurar as suas applications e os seus authentication methods.