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.
+ 
+