FRON-3678 – robots.txt de developers y developers.sandbox (documentation)
Jira: FRON-3678 · MUX-MB-441 · Rama sugerida:
feature/mux-mb-441Fuente:Requerimientos_TI_SEO_Flow_Postedin.xlsx, hoja 1 (filas developers.flow.cl y developers.sandbox.flow.cl) y hoja 4 (noindex preventivo opcional). Ticket multi-repo. Spec principal y secuencia global:flow.cl/docs/specs/active/FRON-3678-ajustes-seo-indexacion-postedin.md. Hermanas:coreyprivate-portal.
1. Contexto
Este repo (Docusaurus) sirve developers.flow.cl y developers.sandbox.flow.cl. El mismo build se publica en los dos, y solo cambian los secrets /<env>/doc-site (BASE_URL, buckets, CloudFront). Despliegue: buildspec.yaml → S3 → CloudFront.
Ambos responden 403 a /robots.txt, y Google trata eso como "sin restricciones". El ticket pregunta si el 403 es intencional (WAF) o un error. Respuesta, según la evidencia: es un error de contenido, no un WAF.
- No existe
static/robots.txtni ningún robots enbuild/. - La respuesta es
Server: AmazonS3,Content-Type: application/xml. Es la firma de S3 para un objeto inexistente sin permiso deListBucket, idéntica aweb.flow.cl/llms.txt, que tampoco existe.
docusaurus.config.js usa url: process.env.BASE_URL, sin noIndex ni trailingSlash. Docusaurus ya genera sitemap.xml.
Detección de ambiente (decisión del 2026-10-06, igual que en flow.cl y private-portal): nueva clave ENV_NAME en el secret /<env>/doc-site. Solo production o prod (únicos valores admitidos para producción) habilitan la indexación. No se infiere desde BASE_URL. Valores pedidos a Infra (2026-10-07, igual que en flow.cl): production en prod y vacía en sandbox (la clave existe; sin valor = no producción).
2. Objetivo
Que developers.flow.cl responda 200 con un robots abierto y que developers.sandbox.flow.cl responda 200 con Disallow: /. Este último se puede aplicar de inmediato, porque tiene 0% indexado.
3. Alcance
| Archivo | Cambio |
|---|---|
docusaurus.config.js | Plugin local con hook postBuild({ outDir }) que escribe robots.txt según ENV_NAME. noIndex: true cuando no es producción (opcional, ver RF-03). |
buildspec.yaml | Agregar ENV_NAME: "/SECRET_ENVIRONMENT/doc-site:ENV_NAME" a secrets-manager. |
Secret /<env>/doc-site → clave ENV_NAME | Se crea en todos los ambientes antes del merge (dev: nosotros; superiores: Infra con instrucciones). Si falta, CodeBuild falla. |
4. No-objetivos
- No se declara
Sitemap:en el robots de developers. El Excel define el contenido exacto sin esa línea; queda como sugerencia en P-02. - No se modifica el WAF ni la configuración de CloudFront.
- No se agregan enlaces nuevos al sandbox en la documentación (sugerencia de la hoja 4, fuera de este ticket técnico).
5. Requisitos funcionales
- RF-01: Si
ENV_NAMEesproductionoprod,build/robots.txt=User-agent: */Disallow:. - RF-02: Con cualquier otro valor (
sandbox,qa,algoo ausente),build/robots.txt=User-agent: */Disallow: /. El build no falla. - RF-03 (opcional, hoja 4): fuera de producción,
noIndex: trueen la config de Docusaurus, que emite<meta name="robots" content="noindex, nofollow">en todas las páginas. - RF-04: Las dos URLs
/robots.txtresponden 200text/plain.
7. Diseño propuesto
// docusaurus.config.js
const isProduction = ['production', 'prod'].includes(process.env.ENV_NAME); // cualquier otro valor → no indexa
// config.noIndex = !isProduction; // RF-03
// plugins: [ function robotsPlugin() { return { name: 'robots-txt', postBuild({ outDir }): Promise<void> } } ]
// → escribe outDir/robots.txt con RF-01 o RF-02
- Comparación exacta, con salida segura por defecto: cualquier valor que no sea el de prod cierra el sitio.
- El robots sale en
build/, que el buildspec ya sube completo conaws s3 cp build ... --recursive. El único cambio del buildspec es mapearENV_NAME. S3 asignatext/plainpor la extensión.txt.
8. Alternativas consideradas
A. Plugin postBuild en docusaurus.config.js (elegida)
- Pros: es visible en el build local y no toca el pipeline.
- Contras: la lógica de ambiente queda en la config.
B. Paso en buildspec.yaml que escribe build/robots.txt
- Pros: no toca código.
- Contras: no se reproduce con
npm run buildlocal. - Se descarta.
C. static/robots.txt fijo
- Pros: es lo más simple.
- Contras: el mismo archivo iría a prod y a sandbox, y o se cierra prod o se deja abierto sandbox.
- Se descarta.
9. Casos borde y errores
- CB-001:
ENV_NAMEausente o distinto deproduction/prod- Escenario: la clave no existe en el secret, o trae otro valor.
- Comportamiento esperado: con cualquier otro valor, el build pasa y queda cerrado (
Disallow: /), también en local sinENV_NAME. Si la clave no existe en el secret, CodeBuild falla al resolversecrets-manager(comportamiento de CodeBuild). - Mitigación: crear la clave en todos los ambientes antes del merge.
- CB-002: El WAF bloquea
/robots.txt, además de que el archivo falta- Escenario: después del deploy sigue respondiendo 403.
- Comportamiento esperado: 200.
- Mitigación: si persiste el 403 con el objeto ya presente en S3, escalar a Infra para permitir
/robots.txten el WAF (hoja 1).
11. Plan de verificación
ENV_NAME=production npm run build(y lo mismo conENV_NAME=prod) →build/robots.txtabierto, sinnoindexen los HTML.ENV_NAME=sandbox npm run buildynpm run build(sin valor) →Disallow: /(ynoindexsi se aplica RF-03).ENV_NAME=algo npm run build→ el build pasa,Disallow: /.- Ambiente de desarrollo (
doc-qa.labs.flwapp.site, distribuciónE12E8WNS59GKLN; requiere VPN por WAF): crearENV_NAMEvacía o distinta deproduction/proden el secret de dev (nosotros), desplegar y verificar concurl <dev>/robots.txt→ 200 yDisallow: /. Luego, instrucciones a Infra para crear la clave en sandbox (vacía) y prod (production) antes del merge. - Post-deploy:
curl -i https://developers.flow.cl/robots.txtycurl -i https://developers.sandbox.flow.cl/robots.txt→ 200 y el contenido de la hoja 1 (criterio 2 de la hoja 1 para sandbox). - Avisar en el ticket que el 403 no era intencional (respuesta a la pregunta para TI).
12. Riesgos y mitigaciones
- R-001: Merge del buildspec antes de crear
ENV_NAMEen algún ambiente- Probabilidad: Media · Impacto: Medio
- Descripción: CodeBuild falla y bloquea los deploys de la documentación.
- Mitigación: es un prerrequisito explícito del merge, con confirmación de Infra en el checklist del MR.
Preguntas abiertas
P-01: ¿cómo distinguir producción?Resuelta (2026-10-06): con la claveENV_NAMEen el secret.- P-02 (Postedin): ¿se agrega
Sitemap: https://developers.flow.cl/sitemap.xmlal robots de prod? Docusaurus ya lo genera.
13. Checklist de aceptación
- RF-01, RF-02 y RF-04 implementados (RF-03 si se decide)
-
ENV_NAMEprobado en dev; clave creada por Infra en sandbox y prod antes del merge - Casos borde manejados (CB-001, CB-002)
- No hay desviaciones del diseño (o están documentadas)
- Build exitoso (
npm run build) conENV_NAME=productionyENV_NAME=sandbox - Respuesta sobre el 403 comentada en el ticket
Notas de implementación (2026-10-06)
Implementado: plugin robots-txt (postBuild) en docusaurus.config.js; ENV_NAME en buildspec.yaml.
Verificado localmente: ENV_NAME=prod npm run build → build/robots.txt = User-agent: * / Disallow:; ENV_NAME=sandbox npm run build → Disallow: /. Ambos builds exitosos.
Decisiones: RF-03 (noIndex en no-prod) no implementado: es opcional y, con Disallow: /, Google no leería el meta. Docusaurus invoca postBuild también para el locale en, por lo que se genera además build/en/robots.txt (inocuo: los buscadores solo leen el de la raíz).
Notas de implementación (2026-10-07)
- Valores de
ENV_NAMEalineados con flow.cl:productionen prod y vacía en sandbox. El código no cambia: vacía equivale a no producción. - Estado previo al deploy, verificado con
curl:doc-qa.labs.flwapp.site/robots.txtresponde 403application/xml,Server: AmazonS3, la misma firma que developers.flow.cl y developers.sandbox.flow.cl. Dev reproduce el problema y sirve para validar el arreglo./y/sitemap.xmlresponden 200. doc-qaestá detrás del WAF de CloudFront: sin VPN responde 403 "Request blocked" en todas las rutas (no confundir con el 403 de S3 del robots).