added config option to configure a webroot for the ui

Author: bwp91

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to `homebridge-config-ui-x` will be documented in this file.
 
 - added config option to advertise the ui over mdns
 - added config option to for inactivity-based session timeout
+- added config option to configure a webroot for the ui
 
 ### Homebridge Dependencies
 

src/core/config/config.interfaces.ts

@@ -10,6 +10,7 @@ export interface StartupConfig {
   }
   cspWsOverride?: string
   debug?: boolean
+  webroot?: string
 }
 
 interface PluginChildBridge {
@@ -70,6 +71,7 @@ export interface HomebridgeUiConfig {
   name: string
   port: number
   host?: '::' | '0.0.0.0' | string
+  webroot?: string
   proxyHost?: string
   auth: 'form' | 'none'
   theme: string

src/core/config/config.service.ts

@@ -46,6 +46,7 @@ export class ConfigService {
   public runningInLinux = (!this.runningInDocker && !this.runningInSynologyPackage && !this.runningInPackageMode && platform() === 'linux')
   public runningInFreeBSD = (platform() === 'freebsd')
   public canShutdownRestartHost = (this.runningInLinux || process.env.UIX_CAN_SHUTDOWN_RESTART_HOST === '1')
+  public originalWebroot: string // set later by setOriginalWebroot()
   public enableTerminalAccess = (this.runningInDocker && process.env.HOMEBRIDGE_CONFIG_UI_TERMINAL !== '0')
     || (this.runningInPackageMode && process.env.HOMEBRIDGE_CONFIG_UI_TERMINAL !== '0')
     || this.runningInSynologyPackage
@@ -229,13 +230,23 @@ export class ConfigService {
       menuMode: this.ui.menuMode || 'default',
       wallpaper: this.ui.wallpaper,
       host: this.ui.host || '',
+      webroot: this.ui.webroot || '',
+      originalWebroot: this.originalWebroot || '',
       proxyHost: this.ui.proxyHost || '',
       homebridgePackagePath: this.ui.homebridgePackagePath,
       disableServerMetricsMonitoring: this.ui.disableServerMetricsMonitoring,
       keepOrphans: this.hbStartupSettings?.keepOrphans || false,
     }
   }
 
+  /**
+   * Set the original webroot that is used (used by main.ts)
+   * @param webroot
+   */
+  public setOriginalWebroot(webroot: string) {
+    this.originalWebroot = webroot
+  }
+
   /**
    * Checks to see if the UI requires a restart due to changed ui or bridge settings
    */

src/core/config/config.startup.ts

@@ -27,6 +27,7 @@ export async function getStartupConfig() {
   }).length
 
   config.host = ipv6 ? '::' : '0.0.0.0'
+  config.webroot = '' // need to set as empty string rather than leaving as undefined
 
   // If no ui settings configured - we are done
   if (!ui) {
@@ -75,5 +76,18 @@ export async function getStartupConfig() {
     process.env.UIX_DEBUG_LOGGING = '0'
   }
 
+  // Preload webroot settings
+  if (ui.webroot && process.env.UIX_DEVELOPMENT !== '1') {
+    // Normalise webroot: remove multiple slashes, ensure single leading slash, no trailing slash
+    let webroot = `/${ui.webroot.toString().trim()}`.replace(/\/+/g, '/').replace(/\/$/, '')
+    if (webroot === '/') {
+      webroot = ''
+    }
+    config.webroot = webroot
+    logger.log(`Setting up the UI on webroot: ${webroot}`)
+  } else {
+    config.webroot = '' // need to set as empty string rather than leaving as undefined
+  }
+
   return config
 }

src/core/spa/spa-html.service.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path'
+import process from 'node:process'
+
+import { exists, readFile, writeFile } from 'fs-extra'
+
+export class SpaHtmlService {
+  /**
+   * Updates the index.html file to use the specified webroot
+   * @param webroot The webroot path (can include leading/trailing slashes, will be normalized)
+   */
+  static async updateIndexHtml(webroot: string): Promise<void> {
+    const indexPath = resolve(process.env.UIX_BASE_PATH, 'public/index.html')
+    if (!(await exists(indexPath))) {
+      return
+    }
+    const originalHtml = await readFile(indexPath, 'utf-8')
+    const normalizedWebroot = this.normalizeWebroot(webroot)
+    const modifiedHtml = this.transformHtmlForWebroot(originalHtml, normalizedWebroot)
+    await writeFile(indexPath, modifiedHtml)
+  }
+
+  /**
+   * Normalizes webroot by removing leading/trailing slashes
+   * @param webroot Raw webroot string
+   * @returns Normalized webroot (empty string if no webroot)
+   */
+  private static normalizeWebroot(webroot: string): string {
+    if (!webroot || webroot === '/') {
+      return ''
+    }
+
+    return webroot.replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '')
+  }
+
+  /**
+   * Transforms HTML to use relative paths with proper base href
+   * @param html Original HTML content
+   * @param webroot Normalized webroot (no leading/trailing slashes)
+   * @returns Modified HTML with correct base href and relative asset paths
+   */
+  private static transformHtmlForWebroot(html: string, webroot: string): string {
+    const baseHref = webroot ? `/${webroot}/` : '/'
+
+    return html
+      .replace(/<base href="[^"]*"(\s*)\/?>/g, `<base href="${baseHref}"$1/>`)
+      .replace(/href="\/(?:.*?\/)?assets\//g, 'href="assets/')
+      .replace(/href="\/(?:.*?\/)?favicon\.ico"/g, 'href="favicon.ico"')
+      .replace(/href="\/(?:.*?\/)?([^"/]+\.(png|svg|webmanifest))"/g, 'href="$1"')
+      .replace(/src="\/(?:.*?\/)?assets\//g, 'src="assets/')
+  }
+}

src/core/spa/spa.filter.ts

@@ -6,14 +6,37 @@ import process from 'node:process'
 import { Catch, NotFoundException } from '@nestjs/common'
 import { readFileSync } from 'fs-extra'
 
+import '../../globalDefaults'
+
 @Catch(NotFoundException)
 export class SpaFilter implements ExceptionFilter {
+  private readonly webroot: string
+
+  constructor() {
+    const envWebroot = process.env.UIX_ORIGINAL_WEBROOT
+    this.webroot = (envWebroot && envWebroot !== globalThis.webroot.errorCode)
+      ? envWebroot
+      : ''
+  }
+
   catch(_exception: HttpException, host: ArgumentsHost) {
     const ctx = host.switchToHttp()
     const req = ctx.getRequest()
     const res = ctx.getResponse()
 
-    if (req.url.startsWith('/api/') || req.url.startsWith('/socket.io') || req.url.startsWith('/assets')) {
+    // Check if request is for API, socket.io, assets, or static files (adjusted for webroot)
+    const urlWithoutWebroot = this.webroot ? req.url.replace(new RegExp(`^${this.webroot}`), '') : req.url
+
+    if (urlWithoutWebroot.startsWith('/api/')
+      || urlWithoutWebroot.startsWith('/socket.io')
+      || urlWithoutWebroot.startsWith('/assets')
+      || urlWithoutWebroot.startsWith('/swagger')
+      || urlWithoutWebroot.match(/\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|webmanifest)$/)) {
+      return res.code(404).send('Not Found')
+    }
+
+    // Only serve SPA for requests that start with webroot (or all requests if no webroot)
+    if (this.webroot && !req.url.startsWith(this.webroot)) {
       return res.code(404).send('Not Found')
     }
 

src/globalDefaults.ts

@@ -13,3 +13,8 @@ globalThis.terminal = {
   // Default buffer size for terminal output in bytes
   bufferSize: 50000,
 }
+
+globalThis.webroot = {
+  // Error code to indicate webroot cannot be used
+  errorCode: 'EACCES',
+}

src/main.ts

@@ -17,6 +17,7 @@ import { AppModule } from './app.module'
 import { ConfigService } from './core/config/config.service'
 import { getStartupConfig } from './core/config/config.startup'
 import { Logger } from './core/logger/logger.service'
+import { SpaHtmlService } from './core/spa/spa-html.service'
 import { SpaFilter } from './core/spa/spa.filter'
 
 import './self-check'
@@ -88,8 +89,21 @@ async function bootstrap(): Promise<NestFastifyApplication> {
   const configService: ConfigService = app.get(ConfigService)
   const logger: Logger = app.get(Logger)
 
-  // Serve index.html without a cache
-  app.getHttpAdapter().get('/', async (req: FastifyRequest, res: FastifyReply) => {
+  // (5) Sort out the webroot - update index.html and set env var for spa filter
+  let realWebroot = startupConfig.webroot || ''
+  try {
+    await SpaHtmlService.updateIndexHtml(startupConfig.webroot)
+    process.env.UIX_ORIGINAL_WEBROOT = startupConfig.webroot
+    configService.setOriginalWebroot(startupConfig.webroot)
+  } catch (error) {
+    logger.warn(`Could not update index.html with webroot ${startupConfig.webroot}: ${error.message}`)
+    realWebroot = ''
+    process.env.UIX_ORIGINAL_WEBROOT = globalThis.webroot.errorCode
+    configService.setOriginalWebroot(globalThis.webroot.errorCode)
+  }
+
+  // (6) Serve index.html without a cache
+  app.getHttpAdapter().get(realWebroot || '/', async (req: FastifyRequest, res: FastifyReply) => {
     res.type('text/html')
     res.header('Cache-Control', 'no-cache, no-store, must-revalidate')
     res.header('Pragma', 'no-cache')
@@ -103,10 +117,11 @@ async function bootstrap(): Promise<NestFastifyApplication> {
     setHeaders(res) {
       res.setHeader('Cache-Control', 'public,max-age=31536000,immutable')
     },
+    ...realWebroot ? { prefix: realWebroot } : {},
   })
 
-  // Set prefix
-  app.setGlobalPrefix('/api')
+  // (8) Set api prefix (including webroot)
+  app.setGlobalPrefix(`${realWebroot || ''}/api`)
 
   // (9) Set up cors
   app.enableCors({
@@ -136,7 +151,7 @@ async function bootstrap(): Promise<NestFastifyApplication> {
     })
     .build()
   const document = SwaggerModule.createDocument(app, options)
-  SwaggerModule.setup('swagger', app, document)
+  SwaggerModule.setup(`${realWebroot}/swagger`.replace(/^\//, ''), app, document)
 
   // (12) Use the spa filter to serve index.html for any non-api routes
   app.useGlobalFilters(new SpaFilter())

src/modules/custom-plugins/plugins-settings-ui/plugins-settings-ui.service.ts

@@ -144,7 +144,7 @@ export class PluginsSettingsUiService {
             serverEnv: ${JSON.stringify(this.configService.uiSettings(true))},
           };
           </script>
-          <script src="${origin || 'http://localhost:4200'}/assets/plugin-ui-utils/ui.js?v=${this.configService.package.version}"></script>
+          <script src="${origin || 'http://localhost:4200'}${origin ? (this.configService.ui.webroot || '') : ''}/assets/plugin-ui-utils/ui.js?v=${this.configService.package.version}"></script>
           <script>
             window.addEventListener('load', () => {
               window.parent.postMessage({action: 'loaded'}, '*');

src/modules/plugins/plugins.service.ts

@@ -521,6 +521,19 @@ export class PluginsService {
 
     const userPlatform = platform()
 
+    // Guard rails to keep users safe!
+    // Here we can throw any error, and it will appear in the UI terminal for the user to see
+
+    // (1) If user has a webroot configured and is trying to install a UI version that doesn't support it
+    if (this.configService.ui.webroot && lt(pluginAction.version, '5.7.1-alpha.0')) {
+      throw new Error(
+        `Cannot install HB UI v${pluginAction.version} when a webroot is configured.\n\r`
+        + 'Please either:\n\r'
+        + ' - Remove the configured webroot, restart Homebridge, then try the install again, or\n\r'
+        + ' - Install HB UI v5.8.0 or later.\n\r\n\r',
+      )
+    }
+
     // Set the default install path
     let installPath = this.configService.customPluginPath
       ? this.configService.customPluginPath