Skip to main content

Frontend Custom Static Resource Mounting Guide

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

Configuration Overview​

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

  • /etc/nginx/custom_conf: Custom Nginx configuration directory. Configuration files in 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 a standalone HTML page (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 Custom Frontend Projects​

This solution supports mounting custom-developed frontend projects (such as React, Vue, Angular, Vite, etc.), regardless of the technology stack.
Before deployment, make sure to correctly configure the project's build path (base) and router base directory (basename).

1. Using a Vite Project as an Example​

Suppose you need to deploy to 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 base path
});

2. Configure React Router Base Directory​

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

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

Reverse Proxying External Services​

Nginx configuration supports standard reverse proxy.
For example, to 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 Backend Services​

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

Mounting Specific Static Files​

Some external systems (such as WeCom) require placing specific verification files under the root domain during integration.
For example, to mount the WW_verify_asD8saBGs.txt file in the root directory, 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, to 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, 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": "Test version 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 core product 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 enhances the scalability and flexible integration capabilities of SERVICEME NEXT, making it suitable for multi-scenario enterprise deployment and customization needs.