Why nginx sub_filter?Por que nginx sub_filter?
Framework agnostic: Works with any frontend. No app changes needed. Easy to disable.
Agnostico de framework: Funciona con cualquier frontend. Sin cambios en la app. Facil de deshabilitar.
Overview
The soleprint sidebar is injected into managed app pages using a hybrid nginx + JavaScript approach. This allows any frontend framework (React, Next.js, static HTML) to receive the sidebar without code modifications.
El sidebar de soleprint se inyecta en las paginas de apps manejadas usando un enfoque hibrido nginx + JavaScript. Esto permite que cualquier framework frontend (React, Next.js, HTML estatico) reciba el sidebar sin modificaciones de codigo.
How It Works Como Funciona
┌─────────────────────────────────────────────────────────────────┐
│ Browser Request │
│ http://room.spr.local.ar/ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Nginx │
│ │
│ 1. Routes /spr/* → soleprint:PORT (sidebar assets + API) │
│ 2. Routes /* → frontend:PORT (app pages) │
│ 3. Injects CSS+JS into HTML responses via sub_filter │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Browser Renders │
│ │
│ 1. Page loads with injected CSS (sidebar styles ready) │
│ 2. sidebar.js executes (deferred, after DOM ready) │
│ 3. JS fetches /spr/api/sidebar/config │
│ 4. JS creates sidebar DOM elements and injects into page │
│ 5. Sidebar appears on left side, pushes content with margin │
└─────────────────────────────────────────────────────────────────┘
Key Design Decisions Decisiones de Diseno Clave
Why inject into </head>?Por que inyectar en </head>?
Next.js and streaming SSR may not include </body> in initial response. </head> is always present.
Next.js y SSR streaming pueden no incluir </body> en la respuesta inicial. </head> siempre esta presente.
Why JS instead of iframe?Por que JS en vez de iframe?
No isolation issues, better UX (no double scrollbars), simpler CSS with margin-left.
Sin problemas de aislamiento, mejor UX (sin doble scrollbar), CSS mas simple con margin-left.
Nginx Configuration Configuracion de Nginx
The nginx config injects CSS+JS into HTML responses:
La config de nginx inyecta CSS+JS en las respuestas HTML:
location / {
proxy_pass http://frontend:PORT;
proxy_set_header Accept-Encoding ""; # Required for sub_filter
# Inject sidebar
sub_filter '</head>'
'<link rel="stylesheet" href="/spr/sidebar.css">
<script src="/spr/sidebar.js" defer></script></head>';
sub_filter_once off;
sub_filter_types text/html;
}Port Allocation Asignacion de Puertos
Each room uses unique ports for concurrent operation:
Cada room usa puertos unicos para operacion concurrente:
| Room | Soleprint | Frontend | Backend |
|---|---|---|---|
| amar | 12000 | 3000 | 8001 |
| dlt | 12010 | 3010 | - |
| sample | 12020 | 3020 | 8020 |
Sidebar Config API API de Config del Sidebar
The sidebar JS fetches configuration from /spr/api/sidebar/config:
El JS del sidebar obtiene configuracion de /spr/api/sidebar/config:
{
"room": "amar",
"soleprint_base": "/spr",
"auth_enabled": true,
"tools": {
"artery": "/spr/artery",
"atlas": "/spr/atlas",
"station": "/spr/station"
}
}Troubleshooting
Sidebar not appearingSidebar no aparece
Check if soleprint is running. Verify nginx has Accept-Encoding "". Hard refresh (Ctrl+Shift+R).
Verificar que soleprint esta corriendo. Verificar que nginx tiene Accept-Encoding "". Refresco forzado (Ctrl+Shift+R).
sub_filter not workingsub_filter no funciona
Ensure proxy_set_header Accept-Encoding "" is set. Check response is text/html.
Asegurar que proxy_set_header Accept-Encoding "" esta seteado. Verificar que la respuesta es text/html.