Saltar a contenido

Despliegue en Google Cloud

Para quién es esta guía

Una guía paso a paso y muy detallada para instalar Gestión Civis en Google Cloud Platform (GCP), pensada para alguien que nunca ha usado Google Cloud. Usaremos los servicios gestionados de Google para la base de datos y el almacenamiento, lo que simplifica el mantenimiento.

¿Qué vamos a montar?

En Google Cloud usaremos tres servicios principales:

flowchart LR
    U["👤 Usuario"] -->|HTTPS| VM["Compute Engine<br/>(servidor: Nginx + backend)"]
    VM --> SQL[("Cloud SQL<br/>PostgreSQL gestionado")]
    VM --> GCS["Cloud Storage<br/>(bucket de ficheros)"]
Servicio de Google Para qué lo usamos
Compute Engine Una máquina virtual (VM) donde corre la aplicación, igual que un servidor normal.
Cloud SQL La base de datos PostgreSQL, gestionada por Google (copias de seguridad y actualizaciones automáticas).
Cloud Storage Un "bucket" donde se guardan los ficheros (documentos, PDF), en lugar del disco del servidor.

¿Por qué este enfoque (máquina virtual)?

Gestión Civis usa componentes que cargan modelos de IA en memoria y generan archivos de índice; eso encaja mejor en una máquina virtual estable que en servicios "sin servidor". Al final de la guía se comenta brevemente la alternativa con Cloud Run para quien la necesite.

Costes

Estos servicios tienen coste. Google ofrece crédito de prueba para empezar. Revisa la facturación y configura alertas de presupuesto (lo vemos al final).

Paso 0. Crear la cuenta y el proyecto

  1. Entra en console.cloud.google.com y accede con una cuenta de Google. Acepta los términos.
  2. Activa la facturación (Billing): Google pedirá una tarjeta; si es tu primera cuenta, normalmente recibes crédito gratuito de bienvenida.
  3. Crea un proyecto nuevo: arriba a la izquierda, junto al logo, pulsa el selector de proyecto → Nuevo proyecto. Ponle un nombre, por ejemplo gestion-civis, y créalo. Asegúrate de tenerlo seleccionado después.

La consola y la línea de comandos

Casi todo se puede hacer con clics en la consola web. Esta guía usa la consola para lo visual y, cuando es más rápido, el botón "Activar Cloud Shell" (icono >_ arriba a la derecha): una terminal de Google ya configurada, sin instalar nada.

Paso 1. Activar los servicios (APIs)

Google exige "activar" cada servicio una vez. En la barra de búsqueda de la consola escribe y entra en "APIs y servicios" → "Biblioteca", y activa (botón Habilitar):

  • Compute Engine API
  • Cloud SQL Admin API
  • Cloud Storage (suele estar ya activa)

Atajo por Cloud Shell

Abre Cloud Shell (>_) y ejecuta: 

gcloud services enable compute.googleapis.com sqladmin.googleapis.com storage.googleapis.com

Paso 2. Crear la base de datos (Cloud SQL)

  1. En el buscador de la consola ve a SQL → Crear instancia → PostgreSQL.
  2. Configura:
  3. ID de instancia: civis-db.
  4. Contraseña del usuario postgres: ponle una fuerte y anótala.
  5. Versión: PostgreSQL 15 (o la que ofrezca).
  6. Región: la misma que usarás para la VM (p. ej. europe-southwest1, Madrid).
  7. Edición/tamaño: para empezar, una configuración pequeña (1–2 vCPU) vale.
  8. Crea la instancia (tarda unos minutos).

Cuando esté lista:

  1. Entra en la instancia → pestaña Bases de datos → Crear base de datos → nombre gestion_civis.
  2. Pestaña Usuarios → Añadir cuenta de usuario → usuario civis con una contraseña fuerte (anótala).
  3. Apunta el nombre de conexión de la instancia (aparece en la página de la instancia, con formato proyecto:region:civis-db). Lo necesitaremos.

Cómo se conectará la VM a Cloud SQL

Usaremos el Cloud SQL Auth Proxy, un pequeño programa que crea un "túnel" seguro. Gracias a él, la aplicación se conecta a localhost:5432 como si la base de datos estuviera en la propia VM, sin abrir la base de datos a Internet.

Paso 3. Crear el bucket de almacenamiento (Cloud Storage)

  1. En el buscador ve a Cloud Storage → Buckets → Crear.
  2. Ponle un nombre único en todo Google (p. ej. civis-ficheros-ayto-xxxx).
  3. Región: la misma que la VM.
  4. Deja el acceso privado (no público): los ficheros son confidenciales.
  5. Crea el bucket y anota su nombre.

Paso 4. Crear la cuenta de servicio (credenciales)

La aplicación necesita "identificarse" ante Cloud Storage. Para eso se usa una cuenta de servicio con una clave (un fichero JSON):

  1. Buscador → IAM y administración → Cuentas de servicio → Crear cuenta de servicio.
  2. Nombre: civis-app. Créala.
  3. Concédele el rol "Storage Object Admin" (para leer/escribir en el bucket).
  4. Una vez creada, entra en ella → pestaña Claves → Agregar clave → Crear clave nueva → tipo JSON. Se descargará un fichero .json: guárdalo bien, lo subiremos a la VM.

Paso 5. Crear la máquina virtual (Compute Engine)

  1. Buscador → Compute Engine → Instancias de VM → Crear instancia.
  2. Configura:
  3. Nombre: civis-vm.
  4. Región/zona: la misma de antes (p. ej. europe-southwest1).
  5. Tipo de máquina: e2-standard-2 (2 vCPU, 8 GB) para empezar; sube a e2-standard-4 si va justo (ver Requisitos).
  6. Disco de arranque: cambia el sistema a Ubuntu 22.04 LTS, tamaño 30–50 GB.
  7. Firewall: marca Permitir tráfico HTTP y Permitir tráfico HTTPS.
  8. Crea la instancia. Cuando aparezca en verde, está lista.

Conectarse a la VM

En la lista de instancias, pulsa el botón SSH de la fila de civis-vm. Se abre una terminal dentro de la VM en el navegador (sin contraseñas ni claves: Google lo gestiona).

A partir de aquí, es casi como la guía de servidor

Dentro de la VM, la instalación es muy parecida a la guía de servidor. Los siguientes pasos la adaptan a Google Cloud (Cloud SQL y Cloud Storage en vez de base de datos y disco locales).

Paso 6. Preparar la VM e instalar dependencias

En la terminal SSH de la VM:

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  python3 python3-venv python3-dev build-essential \
  libpq-dev libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 \
  libcairo2 libffi-dev libxml2 libxslt1.1 fonts-dejavu \
  nginx git curl

(No instalamos PostgreSQL aquí: la base de datos está en Cloud SQL.)

Crea el usuario y la carpeta de la aplicación:

sudo useradd -m -s /bin/bash civis
sudo mkdir -p /opt/gestion-civis && sudo chown civis:civis /opt/gestion-civis

Paso 7. Conectar la VM con Cloud SQL (Auth Proxy)

Descarga el Cloud SQL Auth Proxy y déjalo como servicio permanente:

# Descargar el proxy
curl -o /usr/local/bin/cloud-sql-proxy \
  https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.0/cloud-sql-proxy.linux.amd64
sudo chmod +x /usr/local/bin/cloud-sql-proxy

Crea un servicio para que el túnel esté siempre activo. Sustituye PROYECTO:REGION:civis-db por tu nombre de conexión del Paso 2:

sudo nano /etc/systemd/system/cloud-sql-proxy.service

[Unit]
Description=Cloud SQL Auth Proxy
After=network.target

[Service]
ExecStart=/usr/local/bin/cloud-sql-proxy --port 5432 PROYECTO:REGION:civis-db
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now cloud-sql-proxy
sudo systemctl status cloud-sql-proxy     # debe estar "active (running)"

Ahora la base de datos es accesible en localhost:5432 desde la VM.

Permisos del proxy

La VM, por defecto, usa una cuenta de servicio con permisos suficientes para conectarse a Cloud SQL en el mismo proyecto. Si diera error de permisos, concede a la cuenta de servicio de la VM el rol "Cliente de Cloud SQL" en IAM.

Paso 8. Subir las credenciales del bucket

Necesitamos el fichero JSON de la cuenta de servicio (Paso 4) dentro de la VM. La forma más fácil con la SSH del navegador:

  1. En la ventana de SSH, arriba a la derecha, pulsa el icono de engranaje/subir archivo → Cargar archivo y selecciona el .json descargado.
  2. Quedará en tu carpeta personal. Muévelo a una ruta fija:
sudo mkdir -p /opt/gestion-civis/secrets
sudo mv ~/clave-civis-app*.json /opt/gestion-civis/secrets/gcs.json
sudo chown civis:civis /opt/gestion-civis/secrets/gcs.json
sudo chmod 600 /opt/gestion-civis/secrets/gcs.json

(Ajusta el nombre del fichero al que subiste.)

Paso 9. Instalar el backend

Igual que en un servidor normal, pero con la configuración apuntando a Cloud SQL y Cloud Storage:

sudo su - civis
cd /opt/gestion-civis
git clone <URL-DEL-REPOSITORIO> .
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install gunicorn

Crea el .env:

nano /opt/gestion-civis/.env

SECRET_KEY=pega-aqui-una-cadena-larga-y-aleatoria

# Base de datos: a través del túnel del Cloud SQL Auth Proxy (localhost)
DATABASE_URL=postgresql://civis:CONTRASEÑA-DEL-USUARIO-CIVIS@localhost:5432/gestion_civis

# Almacenamiento en Google Cloud Storage
STORAGE_PROVIDER=gcs
GCS_BUCKET_NAME=civis-ficheros-ayto-xxxx
GOOGLE_APPLICATION_CREDENTIALS=/opt/gestion-civis/secrets/gcs.json

FRONTEND_URL=https://civis.tu-ayuntamiento.es
FRONTEND_ALLOWED_ORIGINS=https://civis.tu-ayuntamiento.es
IA_AUDITORIA_ENABLED=false
GOOGLE_API_KEY=

Prepara la base de datos y comprueba que arranca:

flask db upgrade
python seed.py
gunicorn -w 2 -b 127.0.0.1:5000 "app:create_app()"   # verifica y Ctrl+C
exit

Generar la SECRET_KEY

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

Paso 10. Frontend, servicios y Nginx

A partir de aquí, sigue exactamente los pasos de la guía de servidor, que son idénticos en Google Cloud:

DNS hacia la IP de la VM

Para el HTTPS necesitas que tu dominio apunte a la VM. En la lista de instancias de Compute Engine verás la IP externa de civis-vm. Conviene reservarla como estática (VPC → Direcciones IP) para que no cambie, y crear el registro DNS de tipo A de tu dominio hacia esa IP.

Paso 11. Copias de seguridad y costes

  • Base de datos: Cloud SQL hace copias automáticas si las activas en la configuración de la instancia (recomendado). Revísalo.
  • Ficheros: el bucket de Cloud Storage es muy duradero; puedes activar versionado del objeto para protegerte de borrados.
  • Presupuesto: en Facturación → Presupuestos y alertas, crea una alerta (p. ej. avísame al llegar a X €/mes) para no llevarte sorpresas.

Alternativa: Cloud Run (avanzado)

Para quien prefiera un enfoque sin servidor (paga por uso, escala solo), se puede empaquetar el backend en un contenedor y desplegarlo en Cloud Run, con Cloud SQL y Cloud Storage. Es más elaborado y tiene matices a tener en cuenta:

  • Memoria y arranque: la búsqueda/IA (FAISS + torch) consume mucha memoria y tarda en cargar; habría que asignar bastante RAM y configurar mínimo 1 instancia para evitar arranques en frío.
  • Sistema de ficheros efímero: Cloud Run no guarda nada en disco entre peticiones, así que es obligatorio usar STORAGE_PROVIDER=gcs (los índices de búsqueda también deben persistir en el bucket o reconstruirse).
  • Tareas programadas: el scheduler no puede ser un cron de la máquina; se resuelve con Cloud Scheduler llamando periódicamente a un endpoint, o con un Cloud Run Job que ejecute flask civis-system-run.
  • Frontend: se sirve aparte (Cloud Storage + Cloud CDN, o Firebase Hosting), apuntando las llamadas /api al servicio de Cloud Run.

Recomendación

Si es tu primer despliegue, usa la máquina virtual (Compute Engine) de esta guía: es más predecible y se parece a un servidor tradicional. Considera Cloud Run solo si tienes experiencia con contenedores y necesitas escalado automático.