Instalación de cState: Página de Estado Estática con Hugo

cState es una solución de página de estado ultraligera basada en el generador de sitios estáticos Hugo, diseñada para comunicar el estado de servicios sin necesidad de base de datos ni servidor de aplicaciones. Su arquitectura estática permite alojarla gratuitamente en GitHub Pages o Netlify con tiempos de carga mínimos, gestionando incidentes mediante archivos Markdown versionados en Git.

Requisitos Previos

  • Hugo v0.110.0 o superior instalado localmente
  • Git 2.30+
  • Cuenta en GitHub o Netlify para el alojamiento
  • Node.js 16+ (opcional, para herramientas adicionales)
  • Conocimientos básicos de Markdown y YAML

Instalación de Hugo

# Ubuntu/Debian: instalar Hugo Extended (necesario para cState)
sudo apt-get update
sudo apt-get install -y hugo

# Verificar versión (debe ser extended)
hugo version
# Salida esperada: hugo v0.1xx.x+extended linux/amd64

# Si la versión del repositorio es antigua, instalar manualmente:
HUGO_VERSION="0.121.0"
curl -L "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \
    -o hugo.tar.gz
tar -xzf hugo.tar.gz
sudo mv hugo /usr/local/bin/hugo
hugo version

# CentOS/Rocky Linux
sudo yum install -y hugo
# O instalar manualmente como se muestra arriba

Configuración de cState

Inicializar un nuevo sitio cState:

# Crear el proyecto usando la plantilla oficial de cState
git clone https://github.com/cstate/example mi-estado-servicios
cd mi-estado-servicios

# Inicializar Git y añadir cState como submódulo
git init
git submodule add https://github.com/cstate/cstate themes/cstate

# Verificar la estructura del proyecto
ls -la
# content/     - incidentes y páginas
# static/      - archivos estáticos
# config.yml   - configuración principal

# Construir el sitio en modo desarrollo
hugo server --port 1313

# Acceder en: http://localhost:1313

Configurar el archivo principal config.yml:

cat > config.yml << 'EOF'
# Configuración principal de cState
baseURL: "https://status.mi-dominio.com"
languageCode: "es"
title: "Estado de Nuestros Servicios"
theme: cstate

# Metadatos del sitio
params:
  # Descripción SEO de la página de estado
  description: "Panel de estado en tiempo real de nuestra infraestructura de hosting"
  
  # Logo del sitio (colocar en static/)
  logo: "img/logo.png"
  
  # Colores del tema
  brand: "blue"
  
  # Mostrar el indicador de estado global
  enableAveragePageSpeed: true
  
  # Tiempo de caché del feed RSS (minutos)
  cacheBuster: "v1"
  
  # Configuración de componentes del sistema
  systems:
    - name: Sitio Web Principal
      description: "Panel de control y área de clientes"
      link: "https://mi-dominio.com"
      
    - name: API REST
      description: "API de gestión de servicios"
      link: "https://api.mi-dominio.com"
      
    - name: Red de Hosting
      description: "Conectividad de los servidores"
      
    - name: Servidores VPS
      description: "Infraestructura de servidores virtuales"
      
    - name: Panel de Control
      description: "Interfaz de administración de VPS"
      link: "https://panel.mi-dominio.com"
      
    - name: DNS
      description: "Servidores de nombres de dominio"

# Configuración del feed
outputs:
  home:
    - HTML
    - RSS
    - JSON

# Ignorar ciertos archivos en la generación
ignoreFiles:
  - "\.DS_Store$"

# Versión mínima de Hugo requerida
minVersion: "0.110.0"
EOF

Alojamiento en GitHub Pages

Desplegar automáticamente con GitHub Actions:

# Crear repositorio en GitHub y añadir el origen remoto
git remote add origin https://github.com/TU-USUARIO/status-page.git

# Crear la rama gh-pages (vacía)
git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m "Inicializar rama gh-pages"
git push origin gh-pages

# Volver a la rama principal
git checkout main

# Añadir contenido inicial y hacer commit
git add .
git commit -m "Configuración inicial de cState"
git push origin main

Crear el workflow de GitHub Actions:

mkdir -p .github/workflows

cat > .github/workflows/deploy.yml << 'EOF'
# Workflow para construir y desplegar cState en GitHub Pages
name: Deploy cState

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Clonar repositorio con submódulos
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      # Instalar Hugo Extended
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      # Construir el sitio estático
      - name: Build
        run: hugo --minify

      # Desplegar en la rama gh-pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
EOF

git add .github/
git commit -m "Añadir workflow de despliegue automático"
git push origin main

Alojamiento en Netlify

Configuración para Netlify con despliegue continuo:

# Crear archivo de configuración de Netlify
cat > netlify.toml << 'EOF'
# Configuración de Netlify para cState
[build]
  # Comando de construcción
  command = "hugo --minify"
  # Directorio de publicación
  publish = "public"

[build.environment]
  # Versión de Hugo en Netlify
  HUGO_VERSION = "0.121.0"
  HUGO_ENV = "production"
  HUGO_ENABLEGITINFO = "true"

# Redirecciones para URLs limpias
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

# Cabeceras de seguridad
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"
EOF

git add netlify.toml
git commit -m "Añadir configuración de Netlify"
git push origin main

# Conectar en Netlify:
# 1. Ir a app.netlify.com > New site from Git
# 2. Seleccionar el repositorio
# 3. La configuración se toma de netlify.toml automáticamente

Gestión de Incidentes

Los incidentes se crean como archivos Markdown en content/issues/:

# Crear un nuevo incidente
mkdir -p content/issues

cat > "content/issues/$(date +%Y-%m-%d)-latencia-red.md" << 'EOF'
---
Title: Latencia elevada en la red de hosting
Description: Estamos investigando un incremento en la latencia de red que afecta a algunos servidores VPS.
Date: 2024-03-15T10:30:00+01:00
Resolved: false
ResolvedWhen: 
Severity: degraded
Affected:
  - Red de Hosting
  - Servidores VPS
Section: issue
---

Estamos recibiendo alertas de latencia elevada en nuestra red de hosting. El equipo de infraestructura está investigando la causa raíz.

**Actualización 10:45**: Hemos identificado que el problema está relacionado con un switch de red en el datacenter principal. Se ha escalado al proveedor de conectividad.

**Actualización 11:30**: El proveedor de red ha aplicado una corrección de enrutamiento. Los tiempos de latencia están volviendo a niveles normales.
EOF

# Crear un incidente resuelto (ejemplo histórico)
cat > "content/issues/$(date +%Y-%m-%d -d '3 days ago')-mantenimiento-bbdd.md" << 'EOF'
---
Title: Mantenimiento programado de base de datos
Description: Mantenimiento de optimización de la base de datos principal.
Date: 2024-03-12T02:00:00+01:00
Resolved: true
ResolvedWhen: 2024-03-12T04:30:00+01:00
Severity: notice
Affected:
  - API REST
  - Panel de Control
Section: issue
---

Mantenimiento programado de optimización de la base de datos principal. Se espera disponibilidad reducida del Panel de Control y la API REST durante el período de mantenimiento.

**Estado final**: Mantenimiento completado exitosamente. Todos los servicios han vuelto a operar con normalidad.
EOF

# Regenerar y publicar
git add content/issues/
git commit -m "Añadir incidente: latencia de red"
git push origin main
# GitHub Actions desplegará automáticamente

Grupos de Componentes

Organizar componentes en grupos para mejor visibilidad:

# Actualizar config.yml con grupos de componentes
cat >> config.yml << 'EOF'

# Grupos de componentes del sistema
categories:
  - name: "Servicios Web"
    description: "Servicios orientados al cliente"
    systems:
      - Sitio Web Principal
      - API REST
      - Panel de Control
      
  - name: "Infraestructura"
    description: "Capa de infraestructura de red y cómputo"
    systems:
      - Red de Hosting
      - Servidores VPS
      - DNS
EOF

Soporte Multiidioma

Configurar cState en varios idiomas:

# Configuración multiidioma en config.yml
cat >> config.yml << 'EOF'

# Configuración de idiomas
languages:
  es:
    languageName: "Español"
    weight: 1
    params:
      description: "Estado de nuestros servicios"
  en:
    languageName: "English"
    weight: 2
    params:
      description: "Our service status"
EOF

# Crear traducciones en i18n/
mkdir -p i18n
cat > i18n/es.yaml << 'EOF'
# Traducciones al español para cState
- id: status_operational
  translation: "Operacional"
- id: status_degraded
  translation: "Rendimiento degradado"
- id: status_partial
  translation: "Interrupción parcial"
- id: status_major
  translation: "Interrupción mayor"
- id: all_systems_operational
  translation: "Todos los sistemas operativos"
EOF

Personalización del Tema

Personalizar colores y estilos:

# Crear archivo de estilos personalizados
mkdir -p static/css

cat > static/css/custom.css << 'EOF'
/* Personalización del tema cState */

/* Color de marca personalizado */
:root {
    --color-brand: #1d4ed8;
    --color-success: #15803d;
    --color-warning: #b45309;
    --color-danger: #b91c1c;
}

/* Personalizar el encabezado */
header.masthead {
    border-top: 4px solid var(--color-brand);
}

/* Estilo de los indicadores de estado */
.component-status.operational {
    color: var(--color-success);
}
EOF

# Referenciar el CSS personalizado en config.yml
# Añadir a la sección params:
# customCSS: "css/custom.css"

Solución de Problemas

Hugo no construye el sitio (error de submódulo):

# Actualizar submódulos
git submodule update --init --recursive

# Verificar que el tema está presente
ls themes/cstate/

El sitio muestra contenido desactualizado en GitHub Pages:

# Verificar el estado del workflow en GitHub Actions
# Ir a: repositorio > Actions > ver el último workflow

# Forzar reconstrucción
git commit --allow-empty -m "Forzar reconstrucción"
git push origin main

Los incidentes no aparecen en el sitio:

# Verificar el front matter del archivo Markdown
head -20 content/issues/mi-incidente.md

# La fecha no debe ser en el futuro
# El campo Section debe ser exactamente: issue
# Verificar sintaxis YAML del front matter

Error de versión de Hugo:

# Verificar versión actual
hugo version

# El error "extended" indica que se necesita Hugo Extended
# Descargar la versión extended desde GitHub Releases

Conclusión

cState ofrece una solución de página de estado elegante y de coste cero basada en archivos estáticos, que elimina los vectores de fallo asociados a bases de datos y servidores de aplicaciones. El flujo de trabajo basado en Git proporciona un historial completo y auditable de todos los incidentes, mientras que la integración con GitHub Pages o Netlify garantiza alta disponibilidad de la página de estado incluso cuando la infraestructura principal tiene problemas. La arquitectura estática también significa que la página de estado puede cargarse en milisegundos desde cualquier punto del mundo.