フロントエンドでカスタム静的リソースをマウントするガイド

本ドキュメントでは、SERVICEME NEXT 製品のフロントエンドサービスを通じて、カスタムページ、個別開発のフロントエンドプロジェクト、または外部サービスへのリバースプロキシをマウントする方法を紹介します。

設定概要

serviceme-frontend の Docker イメージには、カスタム Nginx 設定 と 静的リソースのホスティング 用に、それぞれ 2 つのマウント可能なディレクトリが用意されています。

/etc/nginx/custom_conf：カスタム Nginx 設定ディレクトリ。このディレクトリ配下の設定ファイルは、自動的に Nginx のコア server 設定ブロックにマージされます。
/usr/share/nginx/static：静的リソースディレクトリ。カスタム Web ページ、ファイル、またはフロントエンドのビルド成果物をホストするために使用します。

コンテナ起動時に上記ディレクトリをマウントすることで、フロントエンドサービスの内容と動作を柔軟に拡張できます。

カスタム HTML ページのマウント

単独の HTML ページ（例：static/app2/index.html）をホストする必要がある場合は、以下の手順で操作できます。

カスタム設定ファイル custom.conf を作成し、内容を以下のようにします。
```
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";
  }
}
```
この設定は、https://<域名>/app2 へアクセスした際に、指定したページを Nginx が読み込むことを示します。

Docker コンテナを起動します。

Linux / macOS 環境：

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 環境：

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

起動成功後、http://localhost/app2 にアクセスすると、ホストされたページを確認できます。

個別開発のフロントエンドプロジェクトのマウント

この方法では、カスタム開発されたフロントエンドプロジェクト（React、Vue、Angular、Vite など）をマウントできます。
技術スタックに制限はありません。
デプロイ前に、プロジェクトの ビルドパス（base） と ルートルーティングディレクトリ（basename） を正しく設定する必要があります。

1. Vite プロジェクトを例にする場合

localhost/app1 パス配下にデプロイする想定で、vite.config.ts に以下を追加します。

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

export default defineConfig({
  plugins: [react()],
  base: "/app1/", // ビルドのルートパスを指定
});

2. React Router のルートルーティングディレクトリを設定

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

これにより、指定したサブパス配下でアプリケーションが正常に読み込まれることを保証できます。
ビルド完了後、ビルド成果物を static/app1/ ディレクトリに配置し、前述の方法でコンテナを起動すればアクセス可能です。

外部サービスへのリバースプロキシ

Nginx 設定では標準的なリバースプロキシをサポートしています。
たとえば、/app3 パスを外部サイトへプロキシする場合は以下の通りです。

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

この設定は、外部 Web ページ、ドキュメント、またはサードパーティシステムの埋め込みに利用できます。

個別開発のバックエンドサービスへのリバースプロキシ

フロントエンドパス配下で内部コンテナサービス（カスタム納品バックエンドなど）へアクセスする必要がある場合は、以下の設定を使用できます。

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

注意：

フロントエンドコンテナとバックエンドコンテナは同一の Docker ネットワーク上に存在する必要があります；

Docker はコンテナ名（例：serviceme_elc）を自動的にホストドメイン名として解決します。

指定した静的ファイルのマウント

一部の外部システム（例：WeCom）では、連携時にルートドメイン配下へ特定の検証ファイルを配置する必要があります。
たとえば、ルートディレクトリ配下に WW_verify_asD8saBGs.txt ファイルをマウントする必要がある場合は、以下の設定を使用できます。

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

このファイルを ./static/ ディレクトリに配置し、設定と静的ディレクトリをマウントします。

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

製品の静的リソースを上書き

カスタム Nginx 設定の優先度は製品のデフォルト設定より高いため、組み込みの静的リソースを上書きする用途に使用できます。
たとえば、製品の PWA マニフェストとアイコンをカスタマイズする場合は以下の通りです。

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

./static ディレクトリに以下のようなカスタムファイルを配置します。

manifest.webmanifest

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

まとめ

上記の方法により、管理者は製品のコアコードを変更することなく、以下の機能を実現できます。

カスタム Web ページまたは静的リソースを迅速にマウントする；
独立したフロントエンドプロジェクトをデプロイする；
外部または内部サービスへのリバースプロキシを行う；
製品のデフォルトリソースファイルを上書きする。

この仕組みにより、SERVICEME NEXT の拡張性と柔軟な統合能力が大幅に向上し、企業における多様なシナリオでのデプロイやカスタマイズ要件に適しています。

設定概要​

カスタム HTML ページのマウント​

個別開発のフロントエンドプロジェクトのマウント​

1. Vite プロジェクトを例にする場合​

2. React Router のルートルーティングディレクトリを設定​

外部サービスへのリバースプロキシ​

個別開発のバックエンドサービスへのリバースプロキシ​

指定した静的ファイルのマウント​

製品の静的リソースを上書き​

まとめ​