Despliegue en Cloudflare

1.Qué significa «desplegar»

Tu Worker ya corre en tu computadora (lección 10). Desplegar es subirlo a Cloudflare para que viva en una dirección pública con HTTPS, lista para que Meta la llame las 24 horas aunque tu computadora esté apagada.

El proceso tiene cuatro piezas, que ordenaremos en este orden porque cada una depende de la anterior:

2.La cuenta de Cloudflare

1. Entra a dash.cloudflare.com y crea una cuenta con tu correo (es gratuita; no se pide tarjeta para el plan gratuito de Workers, pero verifica las condiciones actuales).
2. Confirma tu correo.
3. No necesitas comprar un dominio: Cloudflare te asigna una dirección gratuita del tipo https://nombre-del-worker.tu-subdominio.workers.dev.

La primera vez que despliegues, Cloudflare te pedirá elegir un subdominio de workers.dev (el «tu-subdominio» de arriba). Se hace una sola vez por cuenta y forma parte de la URL pública de todos tus Workers, así que elige uno neutro y profesional; si trabajas para clientes, no pongas el nombre de un cliente.

3.Wrangler: instalar y autenticar

Wrangler es la línea de comandos oficial de Cloudflare para Workers. En el proyecto de referencia ya viene como dependencia de desarrollo (devDependencies), así que basta:

cd codigo
npm install
npx wrangler --version

 ⛅️ wrangler 4.148.0

Usamos npx wrangler (la copia local del proyecto) para que todos usen la misma versión. Después autentica tu cuenta:

npx wrangler login

Se abre el navegador, inicias sesión en Cloudflare y autorizas a Wrangler (usa OAuth: no copias contraseñas ni claves). Wrangler guarda un token en una carpeta de configuración de tu usuario. Para comprobar con quién estás conectado:

npx wrangler whoami

Verás tu correo, el nombre de la cuenta y su Account ID (un identificador, no un secreto, pero tampoco hace falta publicarlo). Para cerrar sesión, npx wrangler logout.

4.Leer wrangler.toml

wrangler.toml es el archivo donde le dices a Cloudflare qué es tu Worker. Este es el del proyecto, con sus comentarios:

name = "bot-minimarket"
main = "src/worker.js"
compatibility_date = "2026-09-01"

# KV: guarda sesiones, pedidos y los ids de mensajes ya procesados.
[[kv_namespaces]]
binding = "BOT_KV"
id = "00000000000000000000000000000000"          # id de EJEMPLO: reemplázalo
preview_id = "11111111111111111111111111111111"  # id de EJEMPLO para wrangler dev

# Cron: cada 15 minutos corre scheduled() (recordatorios).
[triggers]
crons = ["*/15 * * * *"]

# Variables NO secretas.
[vars]
WA_PHONE_ID = "000000000000000"   # id de EJEMPLO

Hay una distinción que decide la seguridad de tu bot: variables ([vars], van en el archivo y en Git) frente a secretos (se cargan con un comando y nunca se escriben en archivos que subas). Los tres secretos del bot son:

5.Crear el KV de verdad

El KV es la memoria del bot. Hasta ahora, en local, Wrangler usaba uno simulado. En la nube necesitas uno real. Un solo comando lo crea:

npx wrangler kv namespace create BOT_KV

Wrangler crea el namespace en tu cuenta y te muestra su id (una cadena de 32 caracteres hexadecimales). Dos formas de usarlo:

• Copiar ese id y reemplazar el valor id = "0000…" de wrangler.toml.
• Añadir --update-config al comando para que Wrangler edite el archivo por ti (esta opción aparece en npx wrangler kv namespace create --help).

Haz esto una sola vez. El preview_id de ejemplo solo importa si usas wrangler dev --remote (contra la nube); en local no hace falta.

6.Cargar los secretos

Cada secreto se carga con wrangler secret put. El comando te pide el valor por teclado (no se muestra ni queda en el historial de la terminal, a diferencia de pegarlo en una línea de comando):

npx wrangler secret put VERIFY_TOKEN
npx wrangler secret put WA_TOKEN
npx wrangler secret put APP_SECRET

Para VERIFY_TOKEN inventas una frase larga y aleatoria (por ejemplo, tres o cuatro palabras al azar más un número) y la guardas en tu gestor de contraseñas: la volverás a escribir en el panel de Meta. Para WA_TOKEN y APP_SECRET los valores vienen de Meta, y los obtendrás en las lecciones 12 y 13.

Si cargaste todo, puedes ver solo los nombres (nunca los valores):

npx wrangler secret list

Otras dos operaciones útiles: npx wrangler secret delete NOMBRE para borrar uno y npx wrangler secret bulk archivo.json para cargar varios de una vez (hasta 100).

Y en tu computadora sigues usando .dev.vars (que nunca se sube). No son lo mismo: .dev.vars es para wrangler dev en local; wrangler secret put es para la nube.

7.Probar el empaquetado: wrangler deploy --dry-run

Antes de subir nada, pídele a Wrangler que haga todo menos subir. --dry-run compila, comprueba la configuración y se detiene. No toca tu cuenta ni pide credenciales de red:

npx wrangler deploy --dry-run

 ⛅️ wrangler 4.148.0
────────────────────
Total Upload: 49.42 KiB / gzip: 13.76 KiB
Your Worker has access to the following bindings:
Binding                                                 Resource                  
env.BOT_KV (00000000000000000000000000000000)           KV Namespace              
env.WA_PHONE_ID ("000000000000000")                     Environment Variable      

--dry-run: exiting now.

Esta es la salida real del proyecto. Léela como una auditoría:

• Total Upload: 49.42 KiB. El paquete del bot completo pesa unos 49 KiB (13.76 KiB comprimido): worker.js más todos los módulos que importa. Muy por debajo de los límites de tamaño; revisa los vigentes en la documentación de límites.
• Bindings. Son los recursos conectados: env.BOT_KV (KV) y env.WA_PHONE_ID (variable). Fíjate en lo que no aparece: VERIFY_TOKEN, WA_TOKEN y APP_SECRET. No están en el archivo, y así debe ser; viven aparte, como secretos.
• Mientras el id del KV siga siendo el de ejemplo (000…), el dry-run pasa, pero el despliegue real fallaría: es una buena razón para no confiar solo en el dry-run.

Si añades --outdir dist, Wrangler deja el paquete resultante en esa carpeta para que lo inspecciones. Con el bot de referencia se generan worker.js (unos 50 KB) y worker.js.map.

npx wrangler deploy --dry-run --outdir dist

8.El despliegue real

Cuando tengas el KV creado con su id en wrangler.toml y los secretos cargados, desplegar es un comando (no lo ejecutes todavía; ahora solo comprende lo que hará):

npx wrangler deploy

Wrangler va a:

1. empaquetar el Worker (como en el dry-run),
2. subirlo a tu cuenta,
3. publicarlo en https://bot-minimarket.<tu-subdominio>.workers.dev,
4. registrar el cron */15 * * * *,
5. imprimir la URL final y un id de versión (anótalo: sirve para revertir).

Con la URL en mano, repetirás con el Worker real las pruebas de la lección 10:

curl -s https://bot-minimarket.<tu-subdominio>.workers.dev/salud

La respuesta esperada es {"ok":true}. Después, la verificación del webhook con tu token real (cambia los datos):

curl -s -w ' [%{http_code}]\n' "https://bot-minimarket.<tu-subdominio>.workers.dev/webhook?hub.mode=subscribe&hub.verify_token=TU_FRASE&hub.challenge=1158201444"

La respuesta esperada es 1158201444 [200]. Esa misma URL, terminada en /webhook, es la que pegarás en el panel de Meta en la lección 13.

9.Ver qué pasa: wrangler tail

Un Worker en producción no tiene «terminal». Para ver sus console.log y console.error mientras funciona, usas tail, que transmite los registros en vivo a tu terminal:

npx wrangler tail bot-minimarket

Mientras llegan mensajes verás cada petición y los errores que ya conoces: Mensaje fallido ..., Error procesando webhook: .... Algunas opciones de tail (están en npx wrangler tail --help):

Cloudflare también ofrece un panel de Observability (registros históricos) en su sitio web; sus opciones cambian con frecuencia, así que consúltalo en la documentación de Workers Logs cuando lo necesites.

10.Volver atrás: versiones y rollback

Todo despliegue crea una versión nueva. Si publicaste un cambio y el bot empezó a fallar, no hace falta correr a editar código: vuelve a la versión anterior.

npx wrangler deployments list
npx wrangler rollback <id-de-version>

deployments list muestra los 10 despliegues más recientes con sus ids. rollback publica de nuevo la versión que le indiques (sin ella, vuelve a la anterior). Es tu botón de pánico mientras investigas con calma.

Un hábito sano antes de cada despliegue:

1. npm test (las 113 pruebas del proyecto en verde).
2. npx wrangler deploy --dry-run.
3. npx wrangler deploy.
4. curl a /salud y un vistazo a wrangler tail.

11.Errores frecuentes

• Subir .dev.vars o pegar tokens en wrangler.toml. Los secretos van con wrangler secret put. Si se filtran, regenéralos.
• Desplegar con los ids de ejemplo del KV. El dry-run pasa pero el despliegue falla. Reemplaza id por el real.
• Confundir .dev.vars con los secretos de la nube. Cargar .dev.vars no sube nada; la nube necesita secret put.
• Olvidar /webhook en la URL del panel de Meta. El Worker acepta también /, pero la verificación y el POST deben llegar a la misma dirección que registraste.
• No guardar el VERIFY_TOKEN real. Lo necesitarás para registrar el webhook; si lo pierdes, define uno nuevo y vuelve a cargarlo.
• Depurar a ciegas. Con wrangler tail abierto, el 90 % de los fallos de primer despliegue se explican en la primera línea de error.
• Subir cambios sin pasar npm test. Un 401 inesperado por romper la firma se evita con una prueba que ya existe.

12.Apuntes para llevar

• Desplegar es publicar el Worker en una URL pública HTTPS (workers.dev) sin servidor propio.
• Flujo: cuenta de Cloudflare → wrangler login → kv namespace create → secret put → deploy → tail.
• wrangler.toml guarda lo no secreto (nombre, KV, cron, WA_PHONE_ID); los secretos (VERIFY_TOKEN, WA_TOKEN, APP_SECRET) se cargan con wrangler secret put.
• wrangler deploy --dry-run empaqueta y revisa sin subir: el bot de referencia pesa unos 49 KiB.
• wrangler tail muestra los registros en vivo; wrangler rollback vuelve a una versión anterior.
• Límites, precios y menús de Cloudflare cambian: verifica siempre la documentación oficial.

13.Glosario