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.


