CI/CD Cheat Sheet - Gunei ERP

Guía rápida de referencia para deployments y CI/CD

Tabla de Contenidos

Overview Rápido
Deployments por Ambiente
Infraestructura Compartida
Ver Logs
Health Checks
Reiniciar Servicios
Ver Estado
Monitoreo
Red Docker
Docker Compose Features
Troubleshooting Rápido
GitHub Actions Workflows
Rollback
Secrets de GitHub Actions

Overview Rápido

Arquitectura CI/CD

Developer Push
    ↓
GitHub Actions Trigger
    ↓
Build Docker Image
    ↓
Push to GHCR
    ↓
SSH to VPS (ED25519 key)
    ↓
Pull + Deploy
    ↓
Health Check
    ↓
Discord Notification

URLs y Servicios

Servicio	URL	Health Endpoint
Frontend Staging	https://staging-erpfront.gunei.xyz	`/health`
Backend Staging	https://staging-erpback.gunei.xyz	`/status`
Frontend Production	https://erpfront.gunei.xyz	`/health`
Backend Production	https://erpback.gunei.xyz	`/status`
GitHub Actions	https://github.com/gunei-dev/gunei-erp-front/actions	-
GHCR Frontend	https://github.com/orgs/gunei-dev/packages?repo_name=gunei-erp-front	-
GHCR Backend	https://github.com/orgs/gunei-dev/packages?repo_name=gunei-erp-back	-

Estructura de Paths

/opt/apps/gunei-erp/
├── backend/
│   ├── staging/
│   │   └── docker-compose.yml
│   └── production/
│       └── docker-compose.yml
├── frontend/
│   ├── staging/
│   │   └── docker-compose.yml
│   └── production/
│       └── docker-compose.yml
└── infrastructure/
    ├── cloud-sql-proxy/
    │   └── docker-compose.yml
    └── caddy/
        └── docker-compose.yml

Deployments por Ambiente

Staging

bash

# Backend
cd /opt/apps/gunei-erp/backend/staging
docker compose pull backend && docker compose up -d backend

# Frontend
cd /opt/apps/gunei-erp/frontend/staging
docker compose pull frontend && docker compose up -d frontend

Production

bash

# Backend
cd /opt/apps/gunei-erp/backend/production
docker compose pull backend && docker compose up -d backend

# Frontend
cd /opt/apps/gunei-erp/frontend/production
docker compose pull frontend && docker compose up -d frontend

Deploy Completo por Ambiente

bash

# Staging
cd /opt/apps/gunei-erp/backend/staging && docker compose pull backend && docker compose up -d backend
sleep 10
cd /opt/apps/gunei-erp/frontend/staging && docker compose pull frontend && docker compose up -d frontend

# Production
cd /opt/apps/gunei-erp/backend/production && docker compose pull backend && docker compose up -d backend
sleep 10
cd /opt/apps/gunei-erp/frontend/production && docker compose pull frontend && docker compose up -d frontend

Infraestructura Compartida

GCP Cloud SQL (via Proxy)

bash

# Conectar a staging (via backend container)
docker exec -it gunei-backend-staging psql -h cloud-sql-proxy -p 5450 -U dba_dev -d erp-dev

# Conectar a production (via backend container)
docker exec -it gunei-backend-production psql -h cloud-sql-proxy -p 5450 -U dba_dev -d erp

# Test de conexión
docker exec gunei-backend-staging psql -h cloud-sql-proxy -p 5450 -U dba_dev -d erp-dev -c "SELECT 1;"

# Ver databases
docker exec gunei-backend-staging psql -h cloud-sql-proxy -p 5450 -U dba_dev -d erp-dev -c "\l"

# Backup staging (via proxy)
docker exec gunei-backend-staging pg_dump -h cloud-sql-proxy -p 5450 -U dba_dev erp-dev | gzip > backup_staging.sql.gz

# Backup production (via proxy)
docker exec gunei-backend-production pg_dump -h cloud-sql-proxy -p 5450 -U dba_dev erp | gzip > backup_production.sql.gz

# Ver logs del proxy
docker logs cloud-sql-proxy --tail 50

Caddy Shared

bash

# Reload (sin downtime)
docker exec caddy-shared caddy reload --config /etc/caddy/Caddyfile

# Ver logs por ambiente
docker exec caddy-shared cat /var/log/caddy/staging-frontend.log
docker exec caddy-shared cat /var/log/caddy/staging-backend.log
docker exec caddy-shared cat /var/log/caddy/production-frontend.log
docker exec caddy-shared cat /var/log/caddy/production-backend.log

# Validar config
docker exec caddy-shared caddy validate --config /etc/caddy/Caddyfile

Ver Logs

bash

# Staging
docker logs gunei-backend-staging -f
docker logs gunei-frontend-staging -f

# Production
docker logs gunei-backend-production -f
docker logs gunei-frontend-production -f

# Infraestructura
docker logs cloud-sql-proxy -f
docker logs caddy-shared -f

# Logs desde hace X tiempo
docker logs gunei-backend-staging --since 10m
docker logs gunei-backend-production --since 1h

Health Checks

bash

# Staging
curl http://localhost:3000/status  # Backend interno
curl http://localhost:3001/health  # Frontend interno
curl https://staging-erpback.gunei.xyz/status  # Backend público
curl https://staging-erpfront.gunei.xyz/health # Frontend público

# Production
curl http://localhost:3100/status  # Backend interno
curl http://localhost:3101/health  # Frontend interno
curl https://erpback.gunei.xyz/status  # Backend público
curl https://erpfront.gunei.xyz/health # Frontend público

# Scripts
/root/scripts/health-check.sh

Reiniciar Servicios

bash

# Staging completo
docker restart cloud-sql-proxy
docker restart gunei-backend-staging
docker restart gunei-frontend-staging
docker restart caddy-shared

# Production completo
docker restart cloud-sql-proxy
docker restart gunei-backend-production
docker restart gunei-frontend-production
docker restart caddy-shared

# Solo un ambiente
docker restart gunei-backend-staging gunei-frontend-staging
docker restart gunei-backend-production gunei-frontend-production

# Solo el proxy (afecta ambos ambientes)
docker restart cloud-sql-proxy

Ver Estado

bash

# Todos los servicios
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Solo staging
docker ps | grep staging

# Solo production
docker ps | grep production

# Infraestructura
docker ps | grep -E "cloud-sql-proxy|caddy-shared"

# Cuándo se deployó
docker inspect gunei-backend-staging --format='{{.State.StartedAt}}'
docker inspect gunei-backend-production --format='{{.State.StartedAt}}'

Monitoreo

bash

# Scripts
/root/scripts/monitor-logs.sh
/root/scripts/health-check.sh

# Ver recursos por ambiente
docker stats gunei-backend-staging --no-stream
docker stats gunei-backend-production --no-stream

# Comparar ambientes
docker stats gunei-backend-staging gunei-backend-production --no-stream
docker stats gunei-frontend-staging gunei-frontend-production --no-stream

# Todos los recursos
docker stats --no-stream

Red Docker

bash

# Inspeccionar red
docker network inspect gunei-network

# Ver servicios en la red
docker network inspect gunei-network | grep -A 3 "Containers"

# Test conectividad
docker exec gunei-frontend-staging ping gunei-backend-staging
docker exec gunei-backend-staging ping cloud-sql-proxy
docker exec gunei-frontend-production ping gunei-backend-production
docker exec gunei-backend-production ping cloud-sql-proxy

Docker Compose Features

Ver Logging Config

bash

docker inspect gunei-backend-staging | grep -A 10 LogConfig
docker inspect gunei-backend-production | grep -A 10 LogConfig

Ver Timezone

bash

docker exec gunei-backend-staging date
docker exec gunei-backend-production date
docker exec cloud-sql-proxy date

Ver Healthcheck Status

bash

docker inspect gunei-backend-staging --format='{{.State.Health.Status}}'
docker inspect gunei-backend-production --format='{{.State.Health.Status}}'
docker inspect gunei-backend-staging --format='{{json .State.Health}}' | jq

Ver Environment Variables

bash

# Backend
docker exec gunei-backend-staging env | grep -E "DATABASE_URL|NODE_ENV|PORT"
docker exec gunei-backend-production env | grep -E "DATABASE_URL|NODE_ENV|PORT"

# Frontend
docker exec gunei-frontend-staging env | grep -E "API_BASE_URL|ORIGIN|PUBLIC_BASE_URL|TZ"
docker exec gunei-frontend-production env | grep -E "API_BASE_URL|ORIGIN|PUBLIC_BASE_URL|TZ"

Pull Latest Images

bash

# Staging (pull_policy: always hace esto automáticamente)
cd /opt/apps/gunei-erp/backend/staging
docker compose pull backend

# Production
cd /opt/apps/gunei-erp/backend/production
docker compose pull backend

# Verificar versión
docker images | grep gunei-erp-back
docker images | grep gunei-erp-front

Troubleshooting Rápido

Conflicto de Puertos

bash

netstat -tlnp | grep -E "3000|3001|3100|3101"
# Nota: Cloud SQL Proxy (5450) es interno a Docker, no expuesto al host

Verificar Ambiente Correcto

bash

docker exec gunei-backend-staging env | grep DATABASE_URL
docker exec gunei-backend-production env | grep DATABASE_URL

Ver Qué Contenedor Usa Qué Puerto

bash

docker ps --format "table {{.Names}}\t{{.Ports}}"

Container No Arranca

bash

# Ver logs de arranque
docker logs gunei-backend-staging
docker logs gunei-frontend-staging

# Ver exit code
docker inspect gunei-backend-staging --format='{{.State.ExitCode}}'

# Recrear container
cd /opt/apps/gunei-erp/backend/staging
docker compose down backend
docker compose up -d backend

Problemas de Conectividad

bash

# Test conexión backend -> Cloud SQL Proxy
docker exec gunei-backend-staging nc -zv cloud-sql-proxy 5450

# Test conexión frontend -> backend
docker exec gunei-frontend-staging nc -zv gunei-backend-staging 3000

# Ver IP de containers
docker inspect gunei-backend-staging --format='{{.NetworkSettings.Networks.gunei-network.IPAddress}}'
docker inspect cloud-sql-proxy --format='{{.NetworkSettings.Networks.gunei-network.IPAddress}}'

GitHub Actions Workflows

Frontend Workflow

Archivo: .github/workflows/deploy-vps.yml

Trigger:

yaml

on:
  push:
    branches: [develop]
  workflow_dispatch:

Image tags generados:

ghcr.io/gunei-dev/gunei-erp-front:develop
ghcr.io/gunei-dev/gunei-erp-front:develop-<sha>
ghcr.io/gunei-dev/gunei-erp-front:latest

Backend Workflow

Archivo: .github/workflows/deploy-staging.yml

Trigger:

yaml

on:
  push:
    branches: [cicd-githubactions, develop]
  workflow_dispatch:

Image tags generados:

ghcr.io/gunei-dev/gunei-erp-back:staging
ghcr.io/gunei-dev/gunei-erp-back:<branch>-<sha>

Ver Workflows

bash

# GitHub UI
# https://github.com/gunei-dev/gunei-erp-front/actions
# https://github.com/gunei-dev/gunei-erp-back/actions

# Re-run: GitHub UI → Actions → Select run → Re-run all jobs
# Trigger manual: GitHub UI → Actions → Select workflow → Run workflow

Rollback

bash

# 1. Ver tags disponibles
# https://github.com/orgs/gunei-dev/packages

# 2. Pull tag específico
docker pull ghcr.io/gunei-dev/gunei-erp-front:develop-abc1234

# 3. Actualizar docker-compose.yml
cd /opt/apps/gunei-erp/frontend/staging
nano docker-compose.yml
# Cambiar: image: ghcr.io/gunei-dev/gunei-erp-front:develop-abc1234

# 4. Recrear contenedor
docker compose up -d frontend

# 5. Verificar
curl https://staging-erpfront.gunei.xyz/health
docker logs gunei-frontend-staging --tail 20

Secrets de GitHub Actions

Secrets Requeridos

Secret	Valor	Uso
`VPS_HOST`	`ssh.gunei.xyz`	Hostname del VPS para SSH
`VPS_USER`	`root`	Usuario SSH
`VPS_SSH_KEY`	`-----BEGIN OPENSSH PRIVATE KEY-----...`	SSH private key ED25519 completa
`DISCORD_WEBHOOK_URL`	`https://discord.com/api/webhooks/...`	Webhook para notificaciones

Ubicación: Repo → Settings → Secrets and variables → Actions

Trabajar con GHCR

bash

# Login en GHCR
echo $GHCR_TOKEN | docker login ghcr.io -u gunei-dev --password-stdin

# Pull imágenes
docker pull ghcr.io/gunei-dev/gunei-erp-front:develop
docker pull ghcr.io/gunei-dev/gunei-erp-back:staging

# Ver imágenes locales
docker images | grep gunei

# Eliminar imagen local (liberar espacio)
docker rmi ghcr.io/gunei-dev/gunei-erp-front:develop-abc1234

Best Practices

DO

Usar ED25519 keys para SSH
Testear localmente antes de push
Usar tags específicos para rollbacks
Monitorear workflows después del push
Verificar health checks post-deployment
Mantener secrets actualizados

DON'T

No commitear secrets en el repo
No usar RSA-4096 keys
No skipear health checks
No deployar directamente a prod sin testing
No ignorar notificaciones de workflow failures

Última actualización: 29 Enero 2026 Versión: 2.2 Autor: Mikle

Cambios en v2.2:

Migración de PostgreSQL Shared a GCP Cloud SQL via Cloud SQL Proxy
Conexión: cloud-sql-proxy:5450 (interno Docker)
Databases: erp-dev (staging), erp (production)
Usuario: dba_dev

Cambios en v2.1:

URLs actualizadas: staging-erpfront/back.gunei.xyz, erpfront/back.gunei.xyz
VPS_HOST actualizado a ssh.gunei.xyz

CI/CD Cheat Sheet - Gunei ERP #

Tabla de Contenidos #

Overview Rápido #

Arquitectura CI/CD #

URLs y Servicios #

Estructura de Paths #

Deployments por Ambiente #

Staging #

Production #

Deploy Completo por Ambiente #

Infraestructura Compartida #

GCP Cloud SQL (via Proxy) #

Caddy Shared #

Ver Logs #

Health Checks #

Reiniciar Servicios #

Ver Estado #

Monitoreo #

Red Docker #

Docker Compose Features #

Ver Logging Config #

Ver Timezone #

Ver Healthcheck Status #

Ver Environment Variables #

Pull Latest Images #

Troubleshooting Rápido #

Conflicto de Puertos #

Verificar Ambiente Correcto #

Ver Qué Contenedor Usa Qué Puerto #

Container No Arranca #

Problemas de Conectividad #

GitHub Actions Workflows #

Frontend Workflow #

Backend Workflow #

Ver Workflows #

Rollback #

Secrets de GitHub Actions #

Secrets Requeridos #

Trabajar con GHCR #

Best Practices #

DO #

DON'T #

CI/CD Cheat Sheet - Gunei ERP

Tabla de Contenidos

Overview Rápido

Arquitectura CI/CD

URLs y Servicios

Estructura de Paths

Deployments por Ambiente

Staging

Production

Deploy Completo por Ambiente

Infraestructura Compartida

GCP Cloud SQL (via Proxy)

Caddy Shared

Ver Logs

Health Checks

Reiniciar Servicios

Ver Estado

Monitoreo

Red Docker

Docker Compose Features

Ver Logging Config

Ver Timezone

Ver Healthcheck Status

Ver Environment Variables

Pull Latest Images

Troubleshooting Rápido

Conflicto de Puertos

Verificar Ambiente Correcto

Ver Qué Contenedor Usa Qué Puerto

Container No Arranca

Problemas de Conectividad

GitHub Actions Workflows

Frontend Workflow

Backend Workflow

Ver Workflows

Rollback

Secrets de GitHub Actions

Secrets Requeridos

Trabajar con GHCR

Best Practices

DO

DON'T