Skip to main content

FRON-3678 – robots.txt de developers y developers.sandbox (documentation)

Jira: FRON-3678 · MUX-MB-441 · Rama sugerida: feature/mux-mb-441 Fuente: 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: core y private-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.txt ni ningún robots en build/.
  • La respuesta es Server: AmazonS3, Content-Type: application/xml. Es la firma de S3 para un objeto inexistente sin permiso de ListBucket, idéntica a web.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​

ArchivoCambio
docusaurus.config.jsPlugin 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.yamlAgregar ENV_NAME: "/SECRET_ENVIRONMENT/doc-site:ENV_NAME" a secrets-manager.
Secret /<env>/doc-site → clave ENV_NAMESe 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_NAME es production o prod, build/robots.txt = User-agent: * / Disallow:.
  • RF-02: Con cualquier otro valor (sandbox, qa, algo o ausente), build/robots.txt = User-agent: * / Disallow: /. El build no falla.
  • RF-03 (opcional, hoja 4): fuera de producción, noIndex: true en la config de Docusaurus, que emite <meta name="robots" content="noindex, nofollow"> en todas las páginas.
  • RF-04: Las dos URLs /robots.txt responden 200 text/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 con aws s3 cp build ... --recursive. El único cambio del buildspec es mapear ENV_NAME. S3 asigna text/plain por 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 build local.
  • 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_NAME ausente o distinto de production/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 sin ENV_NAME. Si la clave no existe en el secret, CodeBuild falla al resolver secrets-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.txt en el WAF (hoja 1).

11. Plan de verificación​

  • ENV_NAME=production npm run build (y lo mismo con ENV_NAME=prod) → build/robots.txt abierto, sin noindex en los HTML.
  • ENV_NAME=sandbox npm run build y npm run build (sin valor) → Disallow: / (y noindex si se aplica RF-03).
  • ENV_NAME=algo npm run build → el build pasa, Disallow: /.
  • Ambiente de desarrollo (doc-qa.labs.flwapp.site, distribución E12E8WNS59GKLN; requiere VPN por WAF): crear ENV_NAME vacía o distinta de production/prod en el secret de dev (nosotros), desplegar y verificar con curl <dev>/robots.txt → 200 y Disallow: /. 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.txt y curl -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_NAME en 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 clave ENV_NAME en el secret.
  • P-02 (Postedin): ¿se agrega Sitemap: https://developers.flow.cl/sitemap.xml al 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_NAME probado 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) con ENV_NAME=production y ENV_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_NAME alineados con flow.cl: production en 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.txt responde 403 application/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.xml responden 200.
  • doc-qa está 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).