Medipath-K Installation Operation Manual

Version: 2.1 Deployment method: Docker Compose stack

1. Deployment Overview

The system is deployed as one Docker Compose stack. Operations staff do not need to deploy backend and algorithm services separately. Enter the delivered expert-service deployment directory and maintain these two files:

text

.env
docker-compose.yml

Run all start, stop, update, rollback, and troubleshooting commands from this deployment directory.

Script Installation

For online environments, download and run the installation script directly:

bash

curl -fsSL "https://deploy-1328549252.cos.ap-shanghai.myqcloud.com/expert-service/install.sh" -o install.sh
sudo bash install.sh

To review the script before running it:

bash

less install.sh

2. Compose Services

Service	Image	Purpose
`mongo`	`docker.medipath.com.cn/mongo`	Database
`expert-service`	`docker.medipath.com.cn/expert-service:${version}`	Main business service
`alg-0`	`docker.medipath.com.cn/alg:${algVersion}`	Algorithm service 1, port 8080, GPU 0
`alg-1`	`docker.medipath.com.cn/alg:${algVersion}`	Algorithm service 2, port 8081, GPU 1
`node-exporter`	`quay.io/prometheus/node-exporter`	Host monitoring
`dcgm-exporter`	`nvcr.io/nvidia/k8s/dcgm-exporter:4.4.1-4.6.0-ubuntu22.04`	GPU monitoring
`pma`	`docker.medipath.com.cn/pma`	Data helper service

3. docker-compose.yml Example

yaml

services:
  mongo:
    image: docker.medipath.com.cn/mongo
    container_name: mongo
    restart: always
    environment:
      TZ: Asia/Shanghai
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ***
    ports:
      - "27017:27017"
    volumes:
      - ${dataDir}/mongo:/data/db

  expert-service:
    image: docker.medipath.com.cn/expert-service:${version}
    container_name: expert-service
    restart: always
    network_mode: host
    depends_on:
      mongo:
        condition: service_started
      alg-0:
        condition: service_healthy
      alg-1:
        condition: service_healthy
    environment:
      TZ: Asia/Shanghai
      EXPERT_EXPIRE_DAY: 7
      EXPERT_ALG_ENDPOINTS: http://${localIp}:8080,http://${localIp}:8081
      NODE_EXPORT_ENDPOINT: http://${localIp}:9100/metrics
      NODE_EXPORT_METRICS_MOUNTPOINT: /home
    volumes:
      - ./log:/log
      - ${dataDir}:/data
    healthcheck:
      test: curl -f http://localhost:9090/health || exit 1
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s

  alg-0:
    image: docker.medipath.com.cn/alg:${algVersion}
    container_name: alg-0
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
      API_PORT: 8080
    volumes:
      - ${dataDir}:/data
      - ${algCache}:/root/.medipath
    deploy:
      resources:
        limits:
          memory: 40G
        reservations:
          devices:
            - driver: nvidia
              device_ids: [ "0" ]
              capabilities: [ gpu ]
    healthcheck:
      test: curl -f http://localhost:$$API_PORT/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  alg-1:
    image: docker.medipath.com.cn/alg:${algVersion}
    container_name: alg-1
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
      API_PORT: 8081
    volumes:
      - ${dataDir}:/data
      - ${algCache}:/root/.medipath
    deploy:
      resources:
        limits:
          memory: 40G
        reservations:
          devices:
            - driver: nvidia
              device_ids: [ "1" ]
              capabilities: [ gpu ]
    healthcheck:
      test: curl -f http://localhost:$$API_PORT/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  node-exporter:
    image: quay.io/prometheus/node-exporter
    container_name: node-exporter
    restart: always
    network_mode: host
    pid: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - '/:/host:ro,rslave'
    command:
      - '--path.rootfs=/host'

  dcgm-exporter:
    image: nvcr.io/nvidia/k8s/dcgm-exporter:4.4.1-4.6.0-ubuntu22.04
    container_name: dcgm-exporter
    restart: always
    network_mode: host
    cap_add:
      - SYS_ADMIN
    environment:
      - DCGM_EXPORTER_NO_HOSTNAME=1
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [ gpu ]

  pma:
    image: docker.medipath.com.cn/pma
    container_name: pma
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ${dataDir}:/data

For a single-GPU server:

Remove or comment out the alg-1 service.
Remove expert-service.depends_on.alg-1.
Change EXPERT_ALG_ENDPOINTS to only http://${localIp}:8080.

4. Server Requirements

Item	Requirement
OS	Ubuntu Server 22.04/24.04
CPU	8 cores or above
Memory	64 GB or above; 96 GB or above is recommended for two algorithm containers
GPU	NVIDIA GPU, 2 cards recommended
Disk	1 TB or above data disk, SSD/NVMe recommended
Time zone	`Asia/Shanghai`

Docker, Docker Compose plugin, NVIDIA Driver, NVIDIA Container Toolkit, and curl are required. pigz is recommended for offline image import/export.

Pre-deployment checks:

bash

nvidia-smi
docker version
docker compose version
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

5. Port Plan

Port	Service	Description
`9090`	`expert-service`	Main business service
`8080`	`alg-0`	Algorithm service 1
`8081`	`alg-1`	Algorithm service 2
`27017`	`mongo`	MongoDB
`9100`	`node-exporter`	Host metrics

Expose only HTTPS or a unified reverse proxy port publicly. Do not expose 27017, 8080, 8081, or 9100 publicly.

6. Data Directory Plan

Recommended production path:

bash

/home/medipath/app/image/data/expert-service

Create directories:

bash

sudo mkdir -p /home/medipath/app/image/data/expert-service
sudo mkdir -p /home/medipath/app/image/data/expert-service/algCache
sudo chown -R "$USER":"$USER" /home/medipath/app/image/data/expert-service

Directory	Description
`${dataDir}/mongo`	MongoDB data
`${dataDir}`	Expert business data mounted to container `/data`
`${algCache}`	Algorithm cache mounted to container `/root/.medipath`
`./log`	Expert logs mounted to container `/log`

7. .env Configuration

Enter the expert-service deployment directory and edit:

bash

vi .env

Recommended production configuration:

dotenv

version=6.1.0
algVersion=all-in-one
localIp=127.0.0.1
limitMemory=8G
dataDir=/home/medipath/app/image/data/expert-service
algCache=/home/medipath/app/image/data/expert-service/algCache

Key	Description
`version`	`expert-service` image version
`algVersion`	`alg` algorithm image version
`localIp`	Use `127.0.0.1` for single-host deployment; use the algorithm server intranet IP for multi-host deployment
`dataDir`	Data mount directory; must be an absolute path in production
`algCache`	Algorithm cache directory; must be an absolute path in production
`limitMemory`	Reserved field; not currently used by the compose file

If localIp is wrong, algorithm calls will fail.

8. Image Preparation

Online:

bash

docker login docker.medipath.com.cn
docker compose pull

Offline:

bash

pigz -dc update.tar.gz | docker load
docker images

Use the actual image package name delivered on site.

9. Start and Check

Start:

bash

docker compose up -d

Check status:

bash

docker compose ps

Health checks:

bash

curl -f http://127.0.0.1:9090/health
curl -f http://127.0.0.1:8080/health
curl -f http://127.0.0.1:8081/health

For single-GPU deployment, check only the enabled algorithm port.

10. Business Acceptance

Open the system URL or proxy URL.
Log in with an admin or test account.
Upload or open a test slide/image.
Confirm image metadata can be read.
Confirm image tiles display correctly.
Run one algorithm analysis.
Confirm algorithm results are returned.
Confirm the report or result page displays correctly.

11. Common Operations Commands

bash

docker compose ps
docker compose logs -f --tail=200 expert-service
docker compose logs -f --tail=100 alg-0
docker compose logs -f --tail=100 alg-1
docker compose logs -f --tail=100 mongo
docker compose restart expert-service
docker compose restart alg-0 alg-1
docker compose down
docker compose pull
docker compose up -d
nvidia-smi
docker stats
curl -s http://127.0.0.1:9100/metrics | head

12. Logs and Troubleshooting

Expert file log directory:

bash

./log

Container logs:

bash

docker logs expert-service
docker logs alg-0
docker logs alg-1
docker logs mongo

Search for:

text

ERROR
GPU_NOT_AVAILABLE
GPU_CHECK_TIMEOUT
model
Mongo
Connection refused
No such file
Permission denied

13. Update and Rollback

Update:

bash

cp .env .env.bak.$(date +%F)
cp docker-compose.yml docker-compose.yml.bak.$(date +%F)
vi .env
docker compose pull
docker compose up -d

Rollback:

bash

vi .env
docker compose pull
docker compose up -d
docker compose ps
curl -f http://127.0.0.1:9090/health
curl -f http://127.0.0.1:8080/health

For rollback, change version and algVersion back to the previous stable versions. If database recovery is required, stop services first and restore ${dataDir}/mongo.

14. Backup Requirements

Item	Frequency
`.env`	Before every release
`docker-compose.yml`	Before every release
`${dataDir}/mongo`	Daily or before major upgrades
`${dataDir}` business data	Daily
`${algCache}`	As needed
Certificates and keys	On change

Example:

bash

tar -czf expert-config-$(date +%F).tgz .env docker-compose.yml
tar -czf expert-data-$(date +%F).tgz /home/medipath/app/image/data/expert-service

15. Common Troubleshooting

Issue	Common Cause	Action
`alg-0` or `alg-1` unhealthy	GPU unavailable, insufficient VRAM, model load failure	Check `nvidia-smi`, `docker logs alg-0`, and `docker logs alg-1`
`expert-service` unhealthy	Mongo not started, algorithm endpoint unreachable, wrong config	Check `docker logs expert-service` and `.env localIp`
Page opens but algorithm returns no result	Algorithm container not ready, port unreachable, data directory mismatch	Check `8080/8081/health` and `${dataDir}`
Image cannot open	File missing, permission issue, data directory not mounted	Check `${dataDir}` permissions and container `/data`
Image pull failed	Registry not logged in, network issue, wrong version	Run `docker login`, verify `version/algVersion`
GPU visible on host but unavailable in container	NVIDIA Container Toolkit issue	Restart Docker and re-run `docker run --gpus all ... nvidia-smi`
Mongo abnormal	Data directory permission issue or old password mismatch	Check `docker logs mongo` and `${dataDir}/mongo`

16. Final Delivery Checklist

[ ] Docker works.
[ ] NVIDIA container runtime works.
[ ] .env is configured for the site.
[ ] docker compose ps shows services running.
[ ] 9090/health succeeds.
[ ] 8080/health succeeds.
[ ] 8081/health succeeds, except single-GPU deployment.
[ ] Login works.
[ ] Images open correctly.
[ ] Algorithm returns results.
[ ] Logs do not show continuous errors.
[ ] Configuration and data are backed up.
[ ] Current version and rollback version are recorded.

Medipath-K Installation Operation Manual ​

1. Deployment Overview ​

Script Installation ​

2. Compose Services ​

3. docker-compose.yml Example ​

4. Server Requirements ​

5. Port Plan ​

6. Data Directory Plan ​

7. .env Configuration ​

8. Image Preparation ​

9. Start and Check ​

10. Business Acceptance ​

11. Common Operations Commands ​

12. Logs and Troubleshooting ​

13. Update and Rollback ​

14. Backup Requirements ​

15. Common Troubleshooting ​

16. Final Delivery Checklist ​

Medipath-K Installation Operation Manual

1. Deployment Overview

Script Installation

2. Compose Services

3. docker-compose.yml Example

4. Server Requirements

5. Port Plan

6. Data Directory Plan

7. .env Configuration

8. Image Preparation

9. Start and Check

10. Business Acceptance

11. Common Operations Commands

12. Logs and Troubleshooting

13. Update and Rollback

14. Backup Requirements

15. Common Troubleshooting

16. Final Delivery Checklist