Skip to main content

Guide to Mounting Custom Static Resources on the Frontend

This document describes how to mount custom pages, custom-developed 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 for custom Nginx configuration and static resource hosting respectively:

  • /etc/nginx/custom_conf: Custom Nginx configuration directory. Configuration files in this directory will be automatically merged into Nginx's core server configuration block.
  • /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 a Custom HTML Page​

If you need to host a standalone HTML page (for example, 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://<域名>/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 startup succeeds, visit http://localhost/app2 to view the hosted page.

Mounting a Custom-Developed Frontend Project​

This solution supports mounting custom-developed frontend projects (such as React, Vue, Angular, Vite, etc.), with no restriction on the technology stack.
Before deployment, you need to correctly configure the project's build path (base) and route root directory (basename).

1. Using a Vite Project as an Example​

Assume it needs to be deployed under the localhost/app1 path. Add the following to vite.config.ts:

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

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

2. Configure the React Router Route Root Directory​

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

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

Reverse Proxying External Services​

Nginx configuration can support standard reverse proxying.
For example, proxy 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 Proxying Custom-Developed Backend Services​

If you need to access internal container services under a frontend path (such as a custom delivery backend), you can 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 will automatically resolve the container name (such as serviceme_elc) as a host domain name.

Mounting a Specific Static File​

Some external systems (such as WeCom) require placing a specific verification file under the root domain during integration.
For example, if you need to mount the WW_verify_asD8saBGs.txt file under the root directory, you can use the following configuration:

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

Place the 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 configuration, so they can be used to override built-in static resources.
For example, customize the product's PWA manifest and icon:

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

Place custom files in the ./static directory, for example:

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​

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

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

This mechanism greatly improves the extensibility and flexible integration capabilities of SERVICEME NEXT, making it suitable for enterprise multi-scenario deployments and customization requirements.