Configuración y Despliegue

GM Hades Backend se configura exclusivamente mediante variables de entorno. No existe un archivo de configuración YAML ni JSON en tiempo de ejecución para los parámetros del servicio. LoadConfig en internal/config/config.go invoca primero godotenv.Load() para leer un archivo .env si está presente, luego lee cada variable con defaults tipados.

Variables de entorno

Aplicación

Variable	Default	Requerida	Descripción
`APP_NAME`	`gm-hades-backend`	No	Nombre del servicio en los logs
`APP_ENV`	`development`	Sí	`development`, `staging`, `production`
`LOG_LEVEL`	`info`	No	`debug`, `info`, `warn`, `error`

gRPC

Variable	Default	Requerida	Descripción
`GRPC_HOST`	`0.0.0.0`	No	Dirección de bind
`GRPC_PORT`	`50051`	Sí	Puerto TCP para gRPC y HTTP (cmux)

Base de datos ADMON (SQL Server)

Variable	Default	Requerida	Descripción
`ADMON_DB_SERVER`	—	Sí	Hostname o IP del SQL Server
`ADMON_DB_PORT`	`1433`	No	Puerto del SQL Server
`ADMON_DB_USER`	—	Sí	Login del SQL Server
`ADMON_DB_PASSWORD`	—	Sí	Contraseña del SQL Server
`ADMON_DB_NAME`	—	Sí	Nombre de la base de datos
`ADMON_DB_ENCRYPT`	`true`	No	Habilitar cifrado TLS
`ADMON_DB_TRUST_CERT`	`true`	No	Confiar en el certificado del servidor
`SKIP_ADMON_DB`	`false`	No	Iniciar sin ADMON (desactiva servicios SQL Server)

Ejecución de consultas

Variable	Default	Descripción
`QUERY_TIMEOUT_SECONDS`	`300`	Timeout de consulta por defecto (5 minutos)
`QUERY_MAX_RETRIES`	`3`	Reintentos máximos
`QUERY_RETRY_DELAY_MS`	`1000`	Pausa entre reintentos en milisegundos

Multitenant y caché

Variable	Default	Descripción
`MULTITENANT_ENABLED`	`true`	Habilitar resolución de credenciales por RFC
`MULTITENANT_CACHE_TTL_MINUTES`	`15`	TTL de la caché de credenciales
`MULTITENANT_MAX_IN_MEMORY`	`100`	Máximo de tenants en caché simultáneamente

Seguridad y TLS

Variable	Default	Descripción
`ENABLE_TLS`	`false`	Habilitar TLS en el listener gRPC
`TLS_CERT_PATH`	—	Ruta al certificado TLS
`TLS_KEY_PATH`	—	Ruta a la clave privada TLS

Métricas

Variable	Default	Descripción
`ENABLE_METRICS`	`true`	Habilitar endpoint de métricas
`METRICS_PORT`	`9090`	Puerto del endpoint de métricas

Bóveda Fiscal

Variable	Descripción
`BOVEDA_FISCAL_SSH_PASSWORD`	Contraseña SSH para el túnel hacia MariaDB y SFTP
`BOVEDA_FISCAL_DB_PASSWORD`	Contraseña de la base de datos MariaDB
`BOVEDA_FISCAL_SFTP_PASSWORD`	Contraseña del servidor SFTP
`BOVEDA_FISCAL_CONNECTIONS_FILE`	Ruta alternativa al archivo `connections.json`

Validación de seguridad al inicio

ValidateSecurityRequirements() es la primera llamada en main(). Verifica que ADMON_DB_SERVER, ADMON_DB_USER, ADMON_DB_PASSWORD, ADMON_DB_NAME, GRPC_PORT y APP_ENV estén definidas. Si alguna falta en entorno de producción, el proceso termina con código de salida no cero antes de establecer cualquier conexión de red.

Cuando SKIP_ADMON_DB=true, los servicios SQL Server gateway no se registran, pero los servicios de Bóveda Fiscal arrancan normalmente. Este modo es el que utiliza el contenedor gm-hades-boveda.

Build local

# Generar archivos protobuf desde los .proto
make proto

# Compilar binario de desarrollo
make build

# Ejecutar localmente (requiere archivo .env)
make run

# Ejecutar tests con detector de data races
go test ./... -race -count=1 -timeout=120s

Inyección de versión con ldflags

El archivo VERSION en la raíz del repositorio contiene la versión semántica actual. En tiempo de build, ldflags inyectan esta versión y el hash de commit en el paquete internal/version:

go build \
  -ldflags "-X github.com/gmtransport/gm-hades-backend/internal/version.Version=$(cat VERSION) \
            -X github.com/gmtransport/gm-hades-backend/internal/version.CommitHash=$(git rev-parse --short HEAD) \
            -X github.com/gmtransport/gm-hades-backend/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
            -X github.com/gmtransport/gm-hades-backend/internal/version.GoVersion=$(go version | awk '{print $3}')" \
  -o gm-hades-backend ./cmd/server

Esta información está disponible en tiempo de ejecución a través del método gRPC GetServiceInfo y en la UI de documentación HTML.

Dockerfile

El build usa dos etapas:

# Etapa 1: compilación
FROM golang:1.25.5-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags "..." \
    -o gm-hades-backend ./cmd/server

# Etapa 2: imagen final
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/gm-hades-backend .
COPY --from=builder /app/internal/boveda_fiscal/config/connections.json /config/boveda_fiscal/
EXPOSE 50051
CMD ["./gm-hades-backend"]

CGO_ENABLED=0 produce un binario estático que funciona en cualquier imagen Linux sin dependencias de libc.

Docker Compose

Stack completo

docker compose -f deployments/docker/docker-compose.yml up

Servicio	Puerto host	Descripción
`gm-hades-backend`	50051	Gateway SQL Server + Bóveda Fiscal
`gm-hades-boveda`	50052	Solo Bóveda Fiscal (`SKIP_ADMON_DB=true`)

Solo Bóveda Fiscal

docker compose -f deployments/docker/docker-compose.boveda.yml up

Este compose es el que se usa cuando el entorno no tiene acceso al ADMON SQL Server o cuando solo se necesita el servicio de Bóveda Fiscal de forma independiente.

Análisis estático

go vet ./...
staticcheck ./...
gosec ./...
golangci-lint run

La configuración .golangci.yml habilita los linters gosec, errcheck, govet, staticcheck y wrapcheck, entre otros. El linter exhaustruct está desactivado por ser excesivamente restrictivo para DTOs.

CI/CD

El repositorio usa un workflow de trigger (trigger.yml) que invoca un workflow centralizado de deploy (deploy.yml@workflow) en pushes a las ramas main, staging y qa. La rama destino se pasa como parámetro de entrada.

Resumen

Toda la configuración es vía variables de entorno. No hay archivos de configuración YAML en tiempo de ejecución para los parámetros del servicio.
ValidateSecurityRequirements() es la primera operación en main(). Si faltan variables críticas en producción, el proceso termina antes de cualquier conexión de red.
SKIP_ADMON_DB=true permite iniciar solo Bóveda Fiscal sin dependencia del SQL Server ADMON.
El build produce un binario estático con CGO_ENABLED=0. La versión, commit y timestamp se inyectan en tiempo de compilación con ldflags.
Existen dos variantes de compose: stack completo (SQL Server + Bóveda Fiscal) y solo Bóveda Fiscal.