Skip to main content

Frontend Custom Mounting Static Resources Guide

This document describes how to mount custom pages, dedicated frontend projects, or reverse proxy external services through the frontend service of the SERVICEME NEXT product.

Configuration Overview​

The Docker image of serviceme-frontend reserves two mountable directories, used respectively for custom Nginx configuration and static resource hosting:

  • /etc/nginx/custom_conf: Custom Nginx configuration directory. Configuration files under this directory will be automatically merged into the core server block of Nginx.
  • /usr/share/nginx/static: Static resource directory, used to host custom web pages, files, or frontend build outputs.

By mounting the above directories when starting the container, you can flexibly extend the content and behavior of the frontend service.

Mounting Custom HTML Pages​

If you need to host individual HTML pages (e.g., static/app2/index.html), follow these steps:

  1. Create a custom configuration file custom.conf with the following content:

    location /app2 {
      root /usr/share/nginx/static/;
      index index.html index.htm index.shtml;
      try_files $uri $uri/ /index.html;

      if ($request_filename ~* .*\.html$) {
        add_header Cache-Control "no-cache, no-store";
      }
    }

    This configuration instructs Nginx to load the specified page when accessing https://<domain>/app2.

  2. Start the Docker container:

    Linux / macOS environment:

    docker run -p 80:80 \
    -e SML_BACKEND_URL=https://dev.next.serviceme.com/webapi/ \
    -e SML_KNOWLEDGE_BACKEND_URL=https://dev.next.serviceme.com/knowledge-webapi/ \
    -v ./custom.conf:/etc/nginx/custom_conf/custom.conf \
    -v ./static:/usr/share/nginx/static \
    servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

    Windows environment:

    docker run -p 80:80 `
    -e SML_BACKEND_URL=https://dev.next.serviceme.com/webapi/ `
    -e SML_KNOWLEDGE_BACKEND_URL=https://dev.next.serviceme.com/knowledge-webapi/ `
    -v ${PWD}\custom.conf:/etc/nginx/custom_conf/custom.conf `
    -v ${PWD}\static:/usr/share/nginx/static `
    servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

  3. After successful startup, visit http://localhost/app2 to view the hosted page.

Mounting Dedicated Frontend Projects​

This solution supports mounting custom-developed frontend projects (such as React, Vue, Angular, Vite, etc.) with no restriction on technology stack.
Before deployment, the project's build base path and router basename must be correctly configured.

1. Example with a Vite project​

Assuming deployment under the path localhost/app1, add the following in vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "/app1/", // specify build base path
});

2. Configure React Router basename​

createBrowserRouter(routes, {
  basename: import.meta.env.BASE_URL
});

This ensures the application loads correctly under the specified subpath.
After building, place the build output in the static/app1/ directory and start the container as described above to access it.

Reverse Proxy External Services​

Nginx configuration supports standard reverse proxy.
For example, proxying the /app3 path to an external website:

location /app3 {
  proxy_pass https://example.com/;
}

This configuration can be used to embed external web pages, documents, or third-party systems.

Reverse Proxy Dedicated Backend Services​

If you need to access internal container services (such as custom delivery backend) under the frontend path, use the following configuration:

location /custom-backend/ {
  proxy_pass http://serviceme_elc/;
  proxy_connect_timeout 240s;
  proxy_read_timeout 240s;
  proxy_send_timeout 240s;
  proxy_buffering off;
}

Note:

  • The frontend container and backend container must be on the same Docker network;
  • Docker automatically resolves container names (e.g., serviceme_elc) as hostnames.

Mounting Specific Static Files​

Some external systems (such as WeChat Work) require placing specific verification files at the root domain during integration.
For example, to mount the file WW_verify_asD8saBGs.txt at the root directory, use the following configuration:

location = /WW_verify_asD8saBGs.txt {
  root /usr/share/nginx/static/;
}

Place this file in the ./static/ directory and mount the configuration and static directory:

docker run \
-v ./custom.conf:/etc/nginx/custom_conf/custom.conf \
-v ./static:/usr/share/nginx/static \
servicemerelease.azurecr.io/serviceme-frontend:4.0.0-rc.2-build.5

Overriding Product Static Resources​

Custom Nginx configurations have higher priority than the product's default configurations, so they can be used to override built-in static resources.
For example, customizing the product's PWA manifest and icons:

location ~* ^/(manifest.webmanifest|customer-logo.svg)$ {
    root /usr/share/nginx/static/;
}

Place custom files in the ./static directory, such as:

manifest.webmanifest

{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "SERVICEME-Custom",
  "short_name": "SERVICEME",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "lang": "en",
  "scope": "./",
  "description": "Beta configuration",
  "icons": [
    {
      "src": "/customer-logo.svg",
      "sizes": "any",
      "type": "image/svg+xml"
    }
  ]
}

Summary​

With the above solutions, administrators can achieve the following without modifying the product's core code:

  • Quickly mount custom web pages or static resources;
  • Deploy standalone frontend projects;
  • Reverse proxy external or internal services;
  • Override default product resource files.

This mechanism greatly enhances the extensibility and flexible integration capabilities of SERVICEME NEXT, suitable for enterprise multi-scenario deployment and customization needs.