svc-scalar-sandbox

A. Identidad

• service_id: svc-scalar-sandbox
• nombre: Scalar Sandbox Developer Portal
• estado: activo desde 2026-06-02
• owner: Gabi
• criticidad: media
• fecha de alta: 2026-06-02
• ultima revision: 2026-06-03

B. Proposito

• resumen funcional: portal publico de documentacion OpenAPI sanitizada del sandbox
• rol dentro del VPS: experiencia de developer portal sin exponer PostgREST
• por que existe: publicar las APIs sandbox con buen UX sin abrir el backend real

C. Ubicacion

• path VPS: /opt/openclawai/infra/api-docs/scalar-sandbox
• path repo/docs: docs/governance/services/svc-scalar-sandbox.md
• compose file: /opt/openclawai/infra/api-docs/scalar-sandbox/docker-compose.yml
• archivos criticos:
• infra/api-docs/scalar-sandbox/docker-compose.yml
• infra/api-docs/scalar-sandbox/scalar.config.json
• infra/data-foundation/postgrest-sandbox/openapi/*.json

D. Docker

• stack: scalar-sandbox
• container names:
• scalar-sandbox
• image/tag: scalarapi/api-reference:latest
• restart policy: unless-stopped
• networks:
• proxy-network
• bind mounts:
• contratos OpenAPI sanitizados montados readonly en /docs
• published ports:
• ninguno
• internal ports:
• 8080/tcp

E. Red

• redes Docker:
• proxy-network
• red publica/proxy: si, solo via NPM
• quien puede hablar con quien:
• Internet llega a NPM
• NPM llega a scalar-sandbox:8080
• scalar-sandbox no necesita reach a PostgREST
• observaciones de red:
• el servicio no pertenece a pg-sandbox-internal
• mantiene desacoplado el portal del runtime real

F. NPM / Proxy / Dominio

• dominio: developers.alpuntodeventa.com.ar
• proxy host: si
• forward hostname: scalar-sandbox
• forward port: 8080
• SSL: Let's Encrypt
• Force SSL: activo
• HSTS: activo

G. Datos y persistencia

• datos criticos:
• contratos OpenAPI sanitizados
• configuracion Scalar
• que se puede regenerar:
• contenedor
• configuracion runtime
• que NO se puede perder:
• artefactos sanitizados versionados
• que NO hace a proposito:
• reach a PostgREST
• requests reales
• manejo de tokens o secretos

H. Backups

• ruta backup: queda cubierta por backup Git del repo y backup general del VPS
• restore probado: recreable desde Git + docker compose up -d
• RPO: 24 horas por politica base del VPS
• RTO: 10-20 minutos en mismo VPS

I. Usos registrados

• usage_id: use-npm-scalar-sandbox-public
• app/servicio consumidor: svc-nginx-proxy-manager
• proposito: publicacion HTTPS del developer portal sandbox
• red usada: proxy-network
• permisos: reach HTTP interno hacia scalar-sandbox:8080
• criticidad: media
• impacto si falla: cae el portal documental sandbox, pero no el runtime interno

J. Dependencias

• depende de:
• proxy-network
• svc-nginx-proxy-manager
• contratos sanitizados en Git
• servicios que dependen de este:
• portal developers.alpuntodeventa.com.ar

K. Operacion

• como validar salud:
• docker ps --filter name=scalar-sandbox
• docker exec nginx-proxy-manager curl -I http://scalar-sandbox:8080/
• curl -I https://developers.alpuntodeventa.com.ar/
• curl -I https://developers.alpuntodeventa.com.ar/clientes
• como reiniciar:
• docker compose -f infra/api-docs/scalar-sandbox/docker-compose.yml up -d
• como regenerar contenido:
• cd /opt/openclawai/infra/data-foundation/postgrest-sandbox
• bash tools/export-sanitized-openapi.sh
• cd /opt/openclawai
• docker compose -f infra/api-docs/scalar-sandbox/docker-compose.yml up -d

L. Seguridad

• secretos: no usa secretos propios
• exposicion publica: solo via NPM
• hardening:
• sin reach a PostgREST
• sin puertos publicados al host
• boton de prueba real oculto
• contratos sin hosts internos Docker
• /clientes publico debe seguir devolviendo 404

M. Estado y decisiones

• decisiones tomadas:
• montar solo OpenAPI sanitizado
• no conectar Scalar directo al backend
• dejar PostgREST solo interno
• riesgos aceptados:
• el portal es publico, pero describe solo contratos sandbox ficticios