FourZ Control Center · Runbook visual

Instala FourZ
con control y evidencia.

Una guía local e interactiva para preparar servidores, instalar la plataforma y validar cada componente. No requiere publicación: abre este archivo HTML directamente en cualquier navegador.

Regla de operación: usa PowerShell como Administrador. Ejecuta primero cada comando sin -Apply, revisa el plan y sólo entonces aplica cambios.
0 / 0 pasos verificados
Alcance

Una máquina

Gitea, Jenkins, Control Center, Web, WCF y Windows Services.

Rutas base

Convención

C:\FourZ.Deployment
C:\Repos\KidZania_
C:\FourZ.Services

Puertos iniciales

Accesos

Gitea :3000 · Jenkins :8080
Web :20003 · WCF :30003

1. BaseRepositorio y herramientas
→
2. PlataformaGitea + Jenkins
→
3. OperaciónControl Center + IIS
→
4. FourZWeb, WCF y servicios
Paso 01

Preparar directorio e instaladores

Copie o clone el proyecto en C:\FourZ.Deployment. En Tools deben existir Git, NuGet, 7-Zip, .NET Framework, Hosting Bundle, Build Tools, JDK, Gitea y Jenkins.

Set-Location C:\FourZ.Deployment
Get-ChildItem .\Tools
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role BuildAgent
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role Platform
Paso 02

Instalar prerrequisitos

BuildAgent prepara Git, NuGet y MSBuild. Platform prepara Java y valida Gitea/Jenkins.

.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role BuildAgent
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role BuildAgent -Apply
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role Platform
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role Platform -Apply
Restart-Computer
Después del reinicio
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role BuildAgent
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role Platform
java -version
$env:JAVA_HOME
dotnet --list-runtimes

Control Center necesita Microsoft.AspNetCore.App 8.x.

Paso 03

Configurar Gitea y Jenkins

Abra http://<servidor>:3000, complete Gitea, cree administrador, organización fourz y token. Luego abra http://<servidor>:8080, complete Jenkins, cree administrador e instale plugins sugeridos.

Checklist Jenkins
  • Plugins: Pipeline, Git, Credentials Binding, Workspace Cleanup y PowerShell.
  • JDK 21 configurado en Global Tool Configuration.
  • Credenciales Git/Gitea en Jenkins Credentials; jamás dentro del Jenkinsfile.
  • Webhook de Gitea y job Pipeline por componente.
Paso 04

Crear el job de liberación en Jenkins

En Jenkins cree primero una credencial Username with password llamada gitea-fourz, con el usuario y token de Gitea. El job usará esa credencial para clonar repositorios privados. Después configure el usuario y el API Token de Jenkins como variables de máquina y cree el job.

[Environment]::SetEnvironmentVariable('FOURZ_JENKINS_USER','<usuario Jenkins>','Machine')
[Environment]::SetEnvironmentVariable('FOURZ_JENKINS_API_TOKEN','<API Token Jenkins>','Machine')
.\ServerBootstrap\Scripts\New-JenkinsDeploymentJob.ps1 -JenkinsUrl 'http://localhost:8080'
Qué crea y cómo resolver errores 401 y 403

Se crea FourZ-Deployment. Permite elegir ambiente, Website/WCF, organización, repositorio y rama. Build y publish se ejecutan siempre; deploy sólo al activar DEPLOY y aprobarlo.

Si Jenkins devuelve 401 Unauthorized, el token no corresponde al usuario de Jenkins, no se cargó la variable de máquina o ese usuario no tiene Overall/Read, Job/Create y Job/Configure. Si devuelve 403 No valid crumb, copie la versión actual del script: conserva la sesión CSRF al crear el job. Para probar sin guardar nada use -PromptForCredential.

Paso 05

Importar repositorios a Gitea

En Control Center use la sección Repositorios. Guarde tokens como variables de entorno de máquina y habilite la importación; primero revise y después importe los repositorios seleccionados.

[Environment]::SetEnvironmentVariable('FOURZ_AZURE_DEVOPS_PAT','<PAT solo lectura>','Machine')
[Environment]::SetEnvironmentVariable('FOURZ_GITEA_TOKEN','<token Gitea>','Machine')
La importación copia Git y no elimina Azure DevOps. PRs, Boards, permisos, políticas y pipelines se configuran por separado.
Paso 05

Instalar Control Center en IIS

Instale primero sólo Control Center para validar el portal sin modificar Web ni WCF. Cree un DNS interno como controlcenter.fourz.local para el binding del sitio.

.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -ControlCenterOnly
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -ControlCenterOnly -Apply
Validación
  • Publique FourZ.ControlCenter.Web en su ruta configurada.
  • Recicle su App Pool y abra el DNS/binding.
  • Compruebe Dashboard, Logs, IIS, disco y memoria.
Paso 06

Configurar Web, WCF y Windows Services

Clone KidZania y revise rutas, certificados, bindings, App Pools y cuentas antes de aplicar la configuración completa.

New-Item -ItemType Directory -Force C:\Repos
Set-Location C:\Repos
git clone <URL Gitea> KidZania_
Set-Location C:\FourZ.Deployment
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target All
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target All -InstallIis -Apply
Revise siempre Config\website.json, Config\services.json y Config\windows-services.json.
Paso 07

Liberar desde Control Center

En Settings habilite despliegues y confirme URL de Gitea, URL de Jenkins y el job FourZ-Deployment. En Deployments seleccione ambiente, FourZ Web o FourZ WCF, organización, repositorio y rama. El portal consulta Gitea y envía los parámetros a Jenkins.

Primera instalación del sitio

Active Inicializar IIS antes de liberar sólo cuando Web o WCF aún no existe. Jenkins crea App Pool, sitio, bindings y extrae el ZIP base; después compila la rama y la publica. En liberaciones posteriores déjelo desactivado.

Jenkins debe tener la credencial gitea-fourz. El App Pool de Control Center necesita recibir las variables de máquina de Jenkins después de reiniciarlo.

Paso 08

Publicar y verificar

Desde Jenkins ejecute el flujo existente: backup → deploy → smoke test. Ante un fallo, detenga el proceso, preserve logs y aplique rollback desde el flujo de despliegue.

Resultado esperado
  • Web responde en el binding configurado.
  • WCF responde en su binding, inicialmente :30003.
  • App Pools iniciados y los nueve Windows Services seleccionados en ejecución.
  • Control Center informa estado y últimos logs.
  • El despliegue de prueba crea backup antes de reemplazar archivos.
Paso 09

Definir perfiles de ambiente

Configure rutas, sitio IIS, App Pool, respaldo y smoke test por ambiente en Config\deployment-environments.json. Production ya contiene el perfil local; Development y UAT permanecen deshabilitados hasta que se definan sus rutas reales.

Regla de liberacion

Jenkins detiene la ejecucion antes de compilar si el perfil seleccionado no existe o esta deshabilitado. No habilite un ambiente hasta confirmar rutas, binding, App Pool y URL de salud.

Paso 10

Configurar webhook de liberacion

El webhook de Gitea llega a Control Center y se guarda primero en disco. Control Center encola la liberacion para Jenkins; una interrupcion o reinicio del App Pool no pierde el evento.

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Set-GiteaJenkinsWebhook.ps1 `
  -ControlCenterWebhookUrl 'http://10.1.2.62/api/webhooks/gitea/release' `
  -Organization kidnetazure `
  -Repository KidZania_ `
  -BranchFilter ProductionOnPremise
Permisos requeridos

El App Pool de Control Center necesita modificar solamente C:\FourZ.Deployment\Queue\GiteaRelease y C:\FourZ.Deployment\Logs. Consulte el runbook para el comando ACL y para revisar cada entrega.

Paso 11

Validar servicios locales y recuperacion

El Dashboard mide disco, CPU y memoria fisica localmente; tambien detecta IIS, SQL Server y Redis. Toda liberacion crea un unico respaldo antes de reemplazar archivos. Si falla el smoke test, restaura ese mismo respaldo.

.\ServerBootstrap\Scripts\Test-ControlCenterReadiness.ps1
.\ServerBootstrap\Scripts\Test-SqlConnectivity.ps1 -ExpectedDatabase 'FourZ-PROD-Test'
Get-Service Redis
Test-NetConnection 127.0.0.1 -Port 6379
.\Scripts\Rollback.ps1 -Component Website -BackupId '<id-del-backup>'
Limites actuales

SQL usa la variable de maquina FOURZ_SQL_CONNECTION_STRING y nunca guarda ni muestra credenciales. Al reiniciar el App Pool, el Dashboard comprueba la conexion autenticada y valida FourZ-PROD-Test. Development y UAT siguen deshabilitados hasta capturar sus rutas reales y separadas de Production.

Paso 12

Separar contenido por ambiente

Production usa C:\inetpub\wwwroot\Production\web_www.fourz.net y C:\inetpub\wwwroot\Production\svc_www.fourz.net. Los nombres IIS y App Pools se conservan; solo cambia la carpeta fisica.

Set-Location C:\FourZ.Deployment
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 `
  -Apply -InstallIis -Target All -UpdateExistingSitePaths
Importante

Use este comando solo al migrar una instalacion existente hacia Production. Sin el modificador, el instalador se detiene si IIS apunta a otra ruta. Development y UAT seguiran el mismo patron cuando se definan sus bindings y App Pools.

Nodo A

Servicios

Gitea + Jenkins + Control Center + IIS/WCF + Windows Services.

Nodo B

Website

Gitea + Jenkins + Control Center + IIS + Website.

Regla actual

Autónomos

Cada máquina conserva scripts, repositorios, secretos y operación local.

Nodo ServiciosGitea · Jenkins · Control Center · WCF · Servicios
⇄
Nodo WebsiteGitea · Jenkins · Control Center · IIS Website
Paso 01

Definir identidad de cada nodo

Asigne IP, DNS y puertos distintos, por ejemplo controlcenter-services.fourz.local y controlcenter-web.fourz.local.

Paso 02

Preparar ambos servidores

En cada nodo copie FourZ.Deployment, instale BuildAgent/Platform, configure Gitea/Jenkins y despliegue Control Center con los pasos 1 a 5 de la pestaña Servidor único.

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role BuildAgent -Apply
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role Platform -Apply
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -ControlCenterOnly -Apply
Paso 03

Preparar nodo de Servicios

Clone el código localmente, valide la configuración WCF y Windows Services, y aplique sólo el objetivo Services.

.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target Services
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target Services -InstallIis -Apply
Paso 04

Preparar nodo Website

Clone el código localmente, valide la configuración Web, y aplique sólo el objetivo Website.

.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target Website
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -Target Website -InstallIis -Apply
Paso 05

Validar la operación independiente

Ejecute una publicación controlada en ambos nodos. Cada Control Center debe mostrar únicamente sus recursos locales, backups y logs, sin depender de privilegios del otro nodo.

Orden seguro

Siempre

Planear → revisar → respaldar → aplicar → smoke test → documentar.

Secretos

Nunca en Git

Use variables de entorno, Jenkins Credentials o el almacén corporativo aprobado.

Comandos de diagnóstico

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role BuildAgent
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role Platform
Get-Service Gitea, Jenkins
Get-Content .\Config\website.json
Get-Content .\Config\services.json
Get-Content .\Config\windows-services.json

Referencia técnica

El detalle completo sigue en installation-runbook.md. Las decisiones de arquitectura están en distributed-topology.md.

Diagnóstico crítico

Si Control Center no abre después de publicar

404: revisa el binding IIS. 403.14: la carpeta del sitio no recibió la publicación. 500.31: falta el runtime ASP.NET Core 8.x.

Import-Module WebAdministration
Get-WebBinding -Name FourZ.ControlCenter
Test-Path C:\inetpub\wwwroot\controlcenter\web.config
dotnet --list-runtimes
Get-WinEvent -LogName Application -MaxEvents 30 | Where-Object { $_.ProviderName -match 'IIS|AspNetCore' }
El proyecto es net8.0. Debe existir Microsoft.AspNetCore.App 8.0.x. El instalador actual de Tools\DotNet8HostingBundle.exe reporta 10.0.10 y no sirve para esta aplicación: sustitúyelo por un Hosting Bundle 8.0.x aprobado, reinicia Windows y valida nuevamente.
Paso 09

Respaldar el paquete NuGet legado

Antes de la primera liberación, descargue una copia local de Microsoft.ApplicationInsights.Wcf 0.28.0-build06820 y sus dependencias. Así el build no dependerá de que MyGet siga disponible.

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Save-ApplicationInsightsArtifact.ps1
Get-ChildItem .\Artifacts\NuGet\packages -Recurse -Filter *.nupkg
Conserve y respalde Artifacts\NuGet. El restore usa ese origen local primero y luego nuget.org. Este paso es obligatorio aun cuando no se marque Inicializar IIS antes de liberar.
Paso 10

Habilitar Deployments desde Settings

Abra Control Center → Settings, active Despliegues mediante Jenkins, valide Gitea, Jenkins y el job FourZ-Deployment; después presione Guardar configuración.

Import-Module WebAdministration
$appPool = 'FourZ.ControlCenter'
$file = 'C:\inetpub\wwwroot\controlcenter\appsettings.json'
icacls $file /grant "IIS AppPool\${appPool}:(M)"
Restart-WebAppPool -Name $appPool
Si Settings muestra error al guardar

El App Pool no tiene permiso de modificar appsettings.json. Ejecute el bloque anterior como administrador. El permiso se otorga sólo a ese archivo; los tokens siguen en variables de entorno de máquina.

Paso 11

Ejecutar la primera liberación

Desde Deployments seleccione ambiente, Website o Services, organización, repositorio y rama. Marque Inicializar IIS antes de liberar sólo si el sitio aún no existe. El portal llama a Jenkins; ahí marque DEPLOY y apruebe el paso manual.

Antes de reintentar un job fallido
  • Actualice el job con Jenkins\Jenkinsfile.
  • Compruebe la credencial Jenkins gitea-fourz.
  • Verifique que el artefacto NuGet existe.
  • Use Production cuando la rama sea productiva, por ejemplo ProductionOnPremise.
  • No marque Inicializar IIS en liberaciones posteriores.
Pendiente de endurecimiento

Alcance actual y siguientes controles

Control Center funciona por máquina y administra recursos locales. Antes de exponerlo fuera de la red administrativa faltan autenticación, roles, auditoría y HTTPS. SQL continúa como módulo de consulta/preparación; las migraciones requieren integrar la herramienta aprobada.

Paso 12

Activar liberación desatendida por push

Actualiza FourZ-Deployment con Jenkins\Jenkinsfile. El job queda en modo Auto: detecta Website y Services dentro del repositorio y libera sólo los ambientes cuya ruta ya existe. No solicita aprobación manual.

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Set-GiteaJenkinsWebhook.ps1 `
  -Organization kidnetazure `
  -Repository KidZania_ `
  -BranchFilter ProductionOnPremise
Configuración requerida en Jenkins

El script crea un webhook de Gitea que llama directamente al job con credenciales de Jenkins configuradas como variables de máquina. Ejecuta el job una vez manualmente después de pegar el Jenkinsfile; luego haz push a ProductionOnPremise. El webhook no reacciona a ramas de desarrollo.

Paso 13

Instalar y verificar Redis

Redis es requerido localmente por los nodos que hospedan FourZ Web o WCF. El instalador Tools\Redis.msi se ejecuta con el rol IisServer y el servicio debe escuchar solamente en 127.0.0.1:6379.

Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Install-ServerPrerequisites.ps1 -Role IisServer -Apply
.\ServerBootstrap\Scripts\Test-ServerReadiness.ps1 -Role IisServer
Get-Service Redis
netstat -ano | findstr :6379
Resultado esperado: servicio Redis en Running y 127.0.0.1:6379 en LISTENING. No expongas el puerto 6379 a la red.
Paso 14

Alta completa del sitio Control Center

Este es el procedimiento completo para crear el sitio IIS, publicar la aplicación y dejarlo disponible mediante la IP del servidor.

Set-Location C:\FourZ.Deployment
.\EnvironmentInstaller\Scripts\Install-Environment.ps1 -ControlCenterOnly -Apply
dotnet publish .\src\FourZ.ControlCenter.Web\FourZ.ControlCenter.Web.csproj -c Release -o C:\inetpub\wwwroot\controlcenter
Import-Module WebAdministration
Stop-Website -Name 'Default Web Site' -ErrorAction SilentlyContinue
Get-WebBinding -Name 'FourZ.ControlCenter' -Protocol http | ForEach-Object { Remove-WebBinding -Name 'FourZ.ControlCenter' -Protocol http -BindingInformation $_.bindingInformation }
New-WebBinding -Name 'FourZ.ControlCenter' -Protocol http -IPAddress '10.1.2.62' -Port 80 -HostHeader ''
Restart-WebAppPool -Name 'FourZ.ControlCenter'
Test-Path C:\inetpub\wwwroot\controlcenter\web.config
Invoke-WebRequest 'http://10.1.2.62/' -UseBasicParsing
Resultado esperado y correcciones
  • El sitio se llama FourZ.ControlCenter, el App Pool tiene el mismo nombre y la carpeta es C:\inetpub\wwwroot\controlcenter.
  • Abra http://10.1.2.62/, no /home/index.
  • 403.14: faltó publicar. 500.31: instale Hosting Bundle ASP.NET Core 8.x. 404: compruebe el binding IP y que Default Web Site no capture el puerto.
Paso 15

Webhook seguro de Gitea a Control Center

El push llega firmado al portal; el portal valida la firma y solicita Jenkins con Basic Auth y crumb CSRF. Jenkins no se expone a llamadas anónimas.

[Environment]::SetEnvironmentVariable('FOURZ_GITEA_WEBHOOK_SECRET', ([Guid]::NewGuid().ToString('N')), 'Machine')
iisreset /restart
# En el app.ini ACTIVO de Gitea agregue:
# [webhook]
# ALLOWED_HOST_LIST = external,loopback,10.1.2.62
Restart-Service gitea
Set-Location C:\FourZ.Deployment
.\ServerBootstrap\Scripts\Set-GiteaJenkinsWebhook.ps1 `
  -ControlCenterWebhookUrl 'http://10.1.2.62/api/webhooks/gitea/release' `
  -Organization kidnetazure `
  -Repository KidZania_ `
  -BranchFilter ProductionOnPremise
Validación

En Gitea use Redelivery. El resultado debe ser 202 Accepted y Jenkins debe encolar FourZ-Deployment. Si Gitea rechaza la IP, se editó otro app.ini o el servicio no fue reiniciado.