Skip to content

setup.md

Latest commit

 

History

History
684 lines (515 loc) · 15.6 KB

setup.md

File metadata and controls

684 lines (515 loc) · 15.6 KB

Guía de Configuración - Forums Service

Requisitos Previos

  • Docker y Docker Compose (recomendado para ejecución rápida)
  • .NET SDK 8.0 o superior (para ejecución local sin Docker)
  • MongoDB 5.0+ (si se ejecuta fuera de Docker) - Se recomienda MongoDB 6.0
  • RabbitMQ (opcional, para integración con mensajería)
  • Git (para clonar el repositorio)

Variables de Entorno

Tabla Completa de Configuración

Variable Descripción Valor por Defecto Requerida Ejemplo
ASPNETCORE_URLS URLs donde escucha la API http://+:80 (Docker) / https://localhost:5001;http://localhost:5000 (Local) No http://+:8080
ASPNETCORE_ENVIRONMENT Entorno de ejecución Production No Development, Staging, Production
MongoDbSettings__ConnectionString Cadena de conexión a MongoDB mongodb://localhost:27017 Sí mongodb://user:pass@mongo:27017
MongoDbSettings__DatabaseName Nombre de la base de datos - Sí forumsdb
RabbitMqSettings__Host Host de RabbitMQ localhost No rabbitmq, amqp.example.com
RabbitMqSettings__Username Usuario de RabbitMQ - No guest, admin
RabbitMqSettings__Password Contraseña de RabbitMQ - No guest, secret123
TicketsService__BaseUrl URL base del servicio de tickets http://localhost:5005/ No http://tickets-service:80/
Logging__LogLevel__Default Nivel de logs por defecto Information No Debug, Information, Warning
Logging__LogLevel__Microsoft Nivel de logs de Microsoft Warning No Information, Warning, Error

Configuración en appsettings.json

El archivo src/forums-service.Api/appsettings.json contiene la configuración base:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "ConnectionStrings": {
    "MongoDb": "mongodb://<username>:<password>@localhost:27017/<database>?authSource=admin"
  },
  "MongoDbSettings": {
    "DatabaseName": "<database>",
    "ConnectionString": "mongodb://<username>:<password>@localhost:27017"
  },
  "RabbitMqSettings": {
    "Host": "localhost",
    "Username": "<username>",
    "Password": "<password>"
  },
  "TicketsService": {
    "BaseUrl": "http://localhost:5005/"
  },
  "AllowedHosts": "*"
}

⚠️ IMPORTANTE: No commitear credenciales reales. Usar variables de entorno o secretos en producción.

Configuración con Variables de Entorno

En .NET Core, las variables de entorno sobrescriben valores de appsettings.json usando el patrón __ (doble guion bajo):

Ejemplo en Linux/Mac:

export MongoDbSettings__ConnectionString="mongodb://root:example@localhost:27017"
export MongoDbSettings__DatabaseName="forumsdb"
export RabbitMqSettings__Host="rabbitmq"
export RabbitMqSettings__Username="guest"
export RabbitMqSettings__Password="guest"

Ejemplo en Windows (PowerShell):

$env:MongoDbSettings__ConnectionString="mongodb://root:example@localhost:27017"
$env:MongoDbSettings__DatabaseName="forumsdb"

Ejemplo en Docker Compose:

environment:
  - MongoDbSettings__ConnectionString=mongodb://root:example@mongodb:27017
  - MongoDbSettings__DatabaseName=forumsdb

Configuración con Docker

docker-compose.yml

El proyecto incluye un docker-compose.yml que levanta tanto MongoDB como la API:

version: '3.8'

services:
  mongodb:
    image: mongo:latest
    container_name: forums_service_mongo
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: example
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db

  forums-service:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: forums_service_api
    depends_on:
      - mongodb
    environment:
      ASPNETCORE_URLS: http://+:80
      MongoDbSettings__ConnectionString: mongodb://root:example@mongodb:27017/?authSource=admin
      MongoDbSettings__DatabaseName: forumsdb
      TicketsService__BaseUrl: http://host.docker.internal:5005/
    ports:
      - "8082:80"

volumes:
  mongo_data:

Comandos Docker

Levantar todos los servicios

docker-compose up -d
  • MongoDB: Disponible en localhost:27017
  • API: Disponible en http://localhost:8082
  • Swagger: http://localhost:8082/swagger

Ver logs de la API

docker-compose logs -f forums-service

Ver logs de MongoDB

docker-compose logs -f mongodb

Detener los servicios

docker-compose down

Detener y eliminar volúmenes (borra datos)

docker-compose down -v

Reconstruir la imagen de la API

docker-compose build forums-service
docker-compose up -d forums-service

Levantar solo MongoDB

docker-compose up -d mongodb

Dockerfile Explicado

# Etapa 1: Build
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

# Copiar todo el código fuente
COPY . ./

# Restaurar dependencias y compilar
WORKDIR /src/src/forums-service.Api
RUN dotnet restore
RUN dotnet publish -c Release -o /app/publish

# Etapa 2: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app

# Copiar binarios compilados
COPY --from=build /app/publish ./

# Configurar puerto
ENV ASPNETCORE_URLS=http://+:80

# Ejecutar la aplicación
ENTRYPOINT ["dotnet", "forums_service.Api.dll"]

Etapas:

  1. build: Usa la imagen SDK completa para compilar el código
  2. runtime: Usa la imagen ASP.NET más ligera para ejecutar la aplicación compilada

Ventajas:

  • Imagen final más pequeña (~200MB vs ~700MB)
  • Mayor seguridad (no incluye herramientas de compilación)

Construir la imagen manualmente

docker build -t forums-service:latest .

Ejecutar el contenedor manualmente

docker run -d \
  --name forums-service \
  -p 8082:80 \
  -e MongoDbSettings__ConnectionString="mongodb://root:example@host.docker.internal:27017" \
  -e MongoDbSettings__DatabaseName="forumsdb" \
  forums-service:latest

Configuración Local (sin Docker)

Paso 1: Instalar .NET SDK 8.0

Windows/Mac: Descargar desde https://dotnet.microsoft.com/download

Linux (Ubuntu/Debian):

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt update
sudo apt install -y dotnet-sdk-8.0

Verificar instalación:

dotnet --version

Paso 2: Configurar MongoDB Local

Opción A: MongoDB con Docker

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD=example \
  mongo:latest

Opción B: MongoDB nativo (Ubuntu/Debian)

⚠️ Nota: Las instrucciones pueden variar según la versión de Ubuntu. A continuación se muestran comandos para Ubuntu 20.04/22.04.

# Para Ubuntu 22.04 (Jammy) - Instalar gnupg
sudo apt-get install -y gnupg curl

# Importar clave GPG de MongoDB (método actualizado)
curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg \
   --dearmor

# Verificar que la clave fue importada correctamente
if [ -f /usr/share/keyrings/mongodb-server-6.0.gpg ]; then
    echo "✅ Clave GPG importada correctamente"
else
    echo "❌ Error al importar la clave GPG"
    exit 1
fi

# Crear lista de sources (Ubuntu 22.04)
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

# Para Ubuntu 20.04, usar 'focal' en lugar de 'jammy'
# echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

# Instalar MongoDB
sudo apt update
sudo apt install -y mongodb-org

# Iniciar el servicio
sudo systemctl start mongod
sudo systemctl enable mongod

# Verificar que está corriendo
sudo systemctl status mongod

Paso 3: Actualizar appsettings.json

Editar src/forums-service.Api/appsettings.json:

{
  "MongoDbSettings": {
    "DatabaseName": "forumsdb",
    "ConnectionString": "mongodb://root:example@localhost:27017/?authSource=admin"
  }
}

Paso 4: Restaurar dependencias

cd /ruta/al/proyecto
dotnet restore

Paso 5: Ejecutar la aplicación

dotnet run --project src/forums-service.Api/forums-service.Api.csproj

URLs:

  • HTTPS: https://localhost:5001
  • HTTP: http://localhost:5000
  • Swagger: https://localhost:5001/swagger

Paso 6 (Opcional): Configurar HTTPS en desarrollo

Si aparece error de certificado HTTPS:

dotnet dev-certs https --trust

Scripts y Comandos

Scripts de .NET disponibles

El proyecto usa comandos de .NET CLI estándar:

Comando Descripción Ejemplo
dotnet restore Restaura dependencias NuGet dotnet restore
dotnet build Compila el proyecto dotnet build -c Release
dotnet run Ejecuta la aplicación dotnet run --project src/forums-service.Api
dotnet test Ejecuta todos los tests dotnet test
dotnet publish Publica la aplicación dotnet publish -c Release -o ./publish
dotnet clean Limpia archivos de compilación dotnet clean

Comandos Útiles

Compilar la solución completa

dotnet build forums-service.sln

Compilar solo un proyecto

dotnet build src/forums-service.Api/forums-service.Api.csproj

Ejecutar tests con cobertura

dotnet test /p:CollectCoverage=true /p:CoverageReportFormat=opencover

Ejecutar tests de un proyecto específico

dotnet test tests/forums-service.Domain.Tests/forums-service.Domain.Tests.csproj

Publicar para Linux (desde Windows)

dotnet publish -c Release -r linux-x64 --self-contained

Ver lista de proyectos en la solución

dotnet sln forums-service.sln list

Scripts personalizados (Makefile - opcional)

Puedes crear un Makefile para simplificar comandos comunes:

.PHONY: build test run docker-up docker-down clean

build:
	dotnet build -c Release

test:
	dotnet test

run:
	dotnet run --project src/forums-service.Api/forums-service.Api.csproj

docker-up:
	docker-compose up -d

docker-down:
	docker-compose down

docker-logs:
	docker-compose logs -f forums-service

clean:
	dotnet clean
	rm -rf **/bin **/obj

restore:
	dotnet restore

Uso:

make build
make test
make docker-up

Troubleshooting

Error: "Unable to connect to MongoDB"

Causa: MongoDB no está corriendo o la cadena de conexión es incorrecta.

Solución:

# Verificar que MongoDB está corriendo
docker ps | grep mongo

# O en local
sudo systemctl status mongod

# Verificar conectividad
mongo --host localhost --port 27017 -u root -p example

Error: "Port 8082 is already in use"

Causa: Otro servicio está usando el puerto.

Solución:

# Ver qué proceso usa el puerto
sudo lsof -i :8082

# O cambiar el puerto en docker-compose.yml
ports:
  - "8083:80"  # Usar puerto 8083 en lugar de 8082

Error: "Unable to obtain configuration from '...'"

Causa: Faltan variables de configuración requeridas.

Solución: Asegúrate de tener configurado:

  • MongoDbSettings__ConnectionString
  • MongoDbSettings__DatabaseName

Error: Certificado HTTPS no confiable en desarrollo

Causa: Certificado de desarrollo no instalado.

Solución:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Logs no aparecen en Docker

Causa: Nivel de logs muy alto.

Solución: Cambiar nivel de logs en docker-compose.yml:

environment:
  - Logging__LogLevel__Default=Debug

Configuración de Producción

Checklist de Producción

  • Usar secretos externos (Azure Key Vault, AWS Secrets Manager, etc.)
  • Habilitar HTTPS/TLS
  • Configurar CORS si se consume desde frontend
  • Implementar autenticación/autorización (JWT, OAuth2)
  • Configurar rate limiting
  • Habilitar logging estructurado (Serilog + ELK/Seq)
  • Configurar health checks (/health)
  • Implementar circuit breaker para llamadas externas
  • Configurar monitoring (Prometheus + Grafana)
  • Habilitar tracing distribuido (OpenTelemetry)

Ejemplo: Azure App Service

# Configurar connection string como secreto
az webapp config appsettings set \
  --resource-group myResourceGroup \
  --name forums-service \
  --settings \
    MongoDbSettings__ConnectionString="mongodb+srv://user:pass@cluster.mongodb.net" \
    MongoDbSettings__DatabaseName="forumsdb" \
    ASPNETCORE_ENVIRONMENT="Production"

Ejemplo: Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: forums-service-secrets
type: Opaque
stringData:
  mongodb-connection: "mongodb://user:pass@mongo-service:27017"
  mongodb-database: "forumsdb"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: forums-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: forums-service
  template:
    metadata:
      labels:
        app: forums-service
    spec:
      containers:
      - name: forums-service
        image: myregistry/forums-service:latest
        ports:
        - containerPort: 80
        env:
        - name: MongoDbSettings__ConnectionString
          valueFrom:
            secretKeyRef:
              name: forums-service-secrets
              key: mongodb-connection
        - name: MongoDbSettings__DatabaseName
          valueFrom:
            secretKeyRef:
              name: forums-service-secrets
              key: mongodb-database
        - name: ASPNETCORE_ENVIRONMENT
          value: "Production"

Monitoreo y Observabilidad

Health Checks (pendiente de implementar)

Agregar en Program.cs:

builder.Services.AddHealthChecks()
    .AddMongoDb(
        mongodbConnectionString: builder.Configuration["MongoDbSettings:ConnectionString"],
        name: "mongodb",
        timeout: TimeSpan.FromSeconds(3));

app.MapHealthChecks("/health");

Verificar:

curl http://localhost:8082/health

Logs Estructurados con Serilog (pendiente de implementar)

dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File

Program.cs:

using Serilog;

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.File("logs/forums-service-.log", rollingInterval: RollingInterval.Day)
    .CreateLogger();

builder.Host.UseSerilog();

Resumen de Comandos Rápidos

# Quick Start con Docker
docker-compose up -d

# Desarrollo Local
dotnet restore
dotnet run --project src/forums-service.Api

# Tests
dotnet test

# Compilar para producción
dotnet publish -c Release -o ./publish

# Docker manual
docker build -t forums-service .
docker run -p 8082:80 forums-service

# Ver logs
docker-compose logs -f forums-service

# Detener todo
docker-compose down

Recursos Adicionales