Despliegue

IZ-CentralForms puede publicarse en un servidor Windows como una aplicación ASP.NET Core hospedada en IIS. La base de datos debe ejecutarse en una instancia real de SQL Server. LocalDB queda reservado únicamente para desarrollo local.

El despliegue productivo requiere:

Windows Server + IIS + .NET Hosting Bundle + SQL Server real + SMTP externo + HTTPS

Alcance

Campo	Valor
Proyecto	IZ-CentralForms
Tipo de aplicación	ASP.NET Core Web API
Target framework	`net10.0`
Hosting recomendado	IIS
Base de datos	SQL Server real
SMTP	Mailtrap, Resend, SMTP corporativo u otro proveedor autorizado
Ambiente actual	Local
Producción	Pendiente de implementación

Prerrequisitos

Antes de desplegar se debe contar con:

Windows Server.
IIS habilitado.
.NET Hosting Bundle compatible con net10.0.
SQL Server Express, Standard o Enterprise.
Acceso para crear base de datos y ejecutar scripts SQL.
Proveedor SMTP o sandbox autorizado.
Certificado SSL válido para QA/Staging/Producción.
Permisos para crear Application Pool.
Permisos para publicar en la carpeta IIS.
Acceso a logs IIS y Event Viewer.

Flujo general de despliegue

Preparar servidor Windows.
Instalar IIS.
Instalar .NET Hosting Bundle.
Confirmar acceso a SQL Server real.
Crear base de datos con scripts de sql/deploy.
Publicar la API con dotnet publish o scripts/publish-iis.ps1.
Copiar publicación a IIS.
Crear Application Pool.
Configurar appsettings.Production.json.
Registrar origins autorizados.
Validar /health, Swagger si aplica, GET formulario, POST submission y endpoints admin.
Entregar evidencias del despliegue.

Scripts SQL

Ejecutar en orden:

sql/deploy/00-create-database.sql
sql/deploy/01-create-schema.sql
sql/deploy/02-seed-demo.sql
sql/deploy/03-add-demo-destinations.sql
sql/deploy/04-verify-deploy.sql

Script opcional para pruebas desde Swagger en IIS local:

sql/deploy/05-add-localhost-iis-origins.sql

Connection string

Demo con SQL Express

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.\\SQLEXPRESS;Database=CentralFormsDb;Trusted_Connection=True;TrustServerCertificate=True;MultipleActiveResultSets=true"
  }
}

No usar en IIS

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=CentralFormsDb;Trusted_Connection=True;MultipleActiveResultSets=true"
  }
}

Permisos SQL

Si se usa usuario SQL, se recomienda asignar permisos mínimos necesarios sobre CentralFormsDb.

Si se usa Trusted_Connection=True, se debe crear login para el Application Pool:

USE master;

IF NOT EXISTS (
    SELECT 1
    FROM sys.server_principals
    WHERE name = 'IIS APPPOOL\CentralForms.Api'
)
BEGIN
    CREATE LOGIN [IIS APPPOOL\CentralForms.Api] FROM WINDOWS;
END;

USE CentralFormsDb;

IF NOT EXISTS (
    SELECT 1
    FROM sys.database_principals
    WHERE name = 'IIS APPPOOL\CentralForms.Api'
)
BEGIN
    CREATE USER [IIS APPPOOL\CentralForms.Api]
    FOR LOGIN [IIS APPPOOL\CentralForms.Api];
END;

ALTER ROLE db_datareader ADD MEMBER [IIS APPPOOL\CentralForms.Api];
ALTER ROLE db_datawriter ADD MEMBER [IIS APPPOOL\CentralForms.Api];

Para una demo controlada puede usarse temporalmente:

ALTER ROLE db_owner ADD MEMBER [IIS APPPOOL\CentralForms.Api];

Publicar API

Desde la raíz del proyecto:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\publish-iis.ps1

Alternativa manual:

dotnet publish .\CentralForms.Api\CentralForms.Api.csproj -c Release -o .\publish\CentralForms.Api

Copiar el contenido generado desde:

publish/CentralForms.Api

hacia:

C:\inetpub\wwwroot\CentralForms.Api

Configuración productiva

Crear o editar:

C:\inetpub\wwwroot\CentralForms.Api\appsettings.Production.json

Plantilla base:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=SERVIDOR_SQL;Database=CentralFormsDb;User Id=centralforms_user;Password=PASSWORD_SEGURO;TrustServerCertificate=True;MultipleActiveResultSets=true"
  },
  "Swagger": {
    "Enabled": false
  },
  "Seed": {
    "DemoData": false
  },
  "Email": {
    "Host": "smtp.proveedor.com",
    "Port": 587,
    "EnableSsl": true,
    "UserName": "USUARIO_SMTP",
    "Password": "PASSWORD_SMTP",
    "FromEmail": "no-reply@interzone.net",
    "FromName": "CentralForms"
  },
  "Admin": {
    "ApiKeyHash": "HASH_SHA256_DE_LA_ADMIN_KEY"
  },
  "AllowedHosts": "*"
}

Variables de entorno en IIS

Como alternativa a appsettings.Production.json, la configuración sensible puede definirse mediante variables de entorno. ASP.NET Core lee claves jerárquicas usando doble guion bajo __.

ASPNETCORE_ENVIRONMENT=Production
ConnectionStrings__DefaultConnection=Server=SERVIDOR_SQL;Database=CentralFormsDb;User Id=USUARIO_SQL;Password=PASSWORD_SQL;TrustServerCertificate=True;MultipleActiveResultSets=true
Admin__ApiKeyHash=HASH_SHA256_DE_LA_ADMIN_KEY
Email__Host=smtp.proveedor.com
Email__Port=587
Email__EnableSsl=true
Email__UserName=USUARIO_SMTP
Email__Password=PASSWORD_SMTP
Email__FromEmail=no-reply@interzone.net
Email__FromName=CentralForms
Swagger__Enabled=false
Seed__DemoData=false

Configurar IIS

Application Pool

Campo	Valor
Nombre	`CentralForms.Api`
.NET CLR Version	`No Managed Code`
Managed Pipeline Mode	`Integrated`
Identity	`ApplicationPoolIdentity`

Sitio o aplicación

Campo	Valor recomendado
Physical Path	`C:\inetpub\wwwroot\CentralForms.Api`
Application Pool	`CentralForms.Api`
Binding HTTP	Solo para pruebas internas
Binding HTTPS	Obligatorio fuera de local
URL pública	Pendiente según ambiente

Origins autorizados

El valor en AllowedOrigins.OriginUrl debe coincidir exactamente con el header Origin enviado por el navegador. En el código actual, Origin se valida cuando viene informado; para ambientes reales se recomienda exigirlo en los flujos públicos de navegador.

Ejemplos válidos:

http://localhost
https://localhost
https://localhost:7122
https://app.interzone.net

Ejemplos incorrectos:

http://localhost/CentralForms.Api
https://app.interzone.net/formulario

Swagger en IIS

Si la aplicación se publica bajo una ruta virtual, por ejemplo:

http://localhost/CentralForms.Api

Swagger debe usar una ruta relativa para el JSON:

options.SwaggerEndpoint("v1/swagger.json", "CentralForms API v1");

No usar ruta absoluta:

options.SwaggerEndpoint("/swagger/v1/swagger.json", "CentralForms API v1");

porque buscaría el JSON en la raíz del sitio IIS y no dentro de /CentralForms.Api.

Validación del despliegue

Validar en este orden:

GET /health
GET /swagger
GET /api/forms/demo/contacto
POST /api/forms/demo/contacto/submit
GET /api/admin/submissions
GET /api/admin/integration-logs

Headers de prueba

GET formulario:

X-Api-Key: demo-api-key
Origin: http://localhost

POST submit:

X-Api-Key: demo-api-key
X-CSRF-Token: TOKEN_DEL_GET
Origin: http://localhost
Content-Type: application/json

Admin:

X-Admin-Key: demo-admin-key

Validaciones SQL posteriores

Después de un POST exitoso, validar persistencia e integraciones:

USE CentralFormsDb;

SELECT TOP 20 *
FROM Submissions
ORDER BY CreatedAt DESC;

SELECT TOP 20
    Type,
    Target,
    Status,
    StatusCode,
    ErrorMessage,
    StartedAt,
    CompletedAt
FROM IntegrationLogs
ORDER BY StartedAt DESC;

Checklist post-despliegue

Validación	Resultado esperado
`/health` responde	API disponible
Swagger carga	Solo si está habilitado para el ambiente
GET formulario responde	`200 OK` con definición y `csrfToken`
POST submit responde	`200 OK` con `submissionId`
Submission se guarda	Registro visible en `Submissions`
Email se ejecuta	Registro visible en `IntegrationLogs`
Webhook se ejecuta	Registro visible en `IntegrationLogs`
HTTPS activo	Certificado válido
Swagger producción	Deshabilitado o restringido
Seed demo producción	Desactivado

Diagnóstico rápido

Síntoma	Causa probable	Acción
`500.19`	Hosting Bundle no instalado o `web.config` no reconocido	Instalar o reparar Hosting Bundle y ejecutar `iisreset`.
`/health` OK pero GET formulario devuelve `500`	Problema SQL o connection string	Revisar base de datos, permisos y `appsettings.Production.json`.
GET formulario devuelve `404`	`consumerCode` o `formCode` incorrecto	Usar `demo/contacto` o revisar tablas.
POST devuelve `403 Origin`	Falta Origin exacto en `AllowedOrigins`	Insertar Origin exacto, sin path.
POST devuelve `403 CSRF`	Token vencido, reutilizado o de otro formulario	Ejecutar GET nuevamente y usar nuevo token.
POST devuelve `200` pero no llega correo	SMTP o destino email mal configurado	Revisar `FormDestinations`, configuración `Email` e `IntegrationLogs`.
Swagger no carga JSON	Ruta Swagger absoluta bajo ruta virtual	Usar `v1/swagger.json` como ruta relativa.

Rollback

Detener sitio o aplicación IIS.
Restaurar carpeta publicada anterior.
Restaurar appsettings.Production.json anterior si cambió.
Restaurar backup de base de datos si hubo migración destructiva.
Iniciar sitio IIS.
Validar /health.
Validar GET formulario.
Validar POST submit.

Evidencia requerida

El responsable del despliegue debe entregar:

URL publicada.
Fecha y hora de publicación.
Versión, commit o paquete publicado.
Resultado de /health.
Evidencia de Swagger si aplica.
Evidencia de GET formulario.
Evidencia de POST submit.
Evidencia de submission en base de datos o admin endpoint.
Evidencia de IntegrationLogs.
Observaciones y errores encontrados.