Palgo Self-Deployment Operation Manual

Version: 1.0 Deployment method: Docker Compose application stack

1. Deployment Overview

Palgo is deployed as one Docker Compose application stack. Operations staff should enter the delivered palgo deployment directory and maintain these two files:

.env
docker-compose.yml

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

2. Service List

Service	Container	Image	Port	Purpose
train-service	train-service	docker.medipath.com.cn/palgo/train-service	59999	Training task service
alg-service	palgo-alg	docker.medipath.com.cn/palgo/alg-service	58888	Palgo algorithm/business algorithm service
search-service	search-service	docker.medipath.com.cn/palgo/search-service	48888	Search service using local lucene directory
backend-service	backend-service	docker.medipath.com.cn/palgo/backend-service	18888	Main backend service
tenant-service	tenant-service	docker.medipath.com.cn/palgo/tenant-service	28888	Tenant service
project-service	project-service	docker.medipath.com.cn/palgo/project-service	38888	Project service and Socket JS endpoint
case-service	case-service	docker.medipath.com.cn/case-service	18082	Case service

All services use network_mode: host, so ports are occupied directly on the host.

3. Prerequisite Service Stack

The Palgo docker-compose.yml starts application services only. It does not include MongoDB, MinIO, RabbitMQ, Keycloak, or the base algorithm containers. These prerequisite services are provided by the delivered esb deployment directory.

Required startup order:

1. Start the esb prerequisite service stack first.
2. Confirm MinIO, MongoDB, RabbitMQ, algorithm containers, and related services are healthy.
3. Start the palgo application service stack.

esb/docker-compose.yml service list:

Service	Container	Port	Purpose
minio-1	minio-1	9000, 9001	Object storage and console
mongo	mongo	27017	MongoDB
postgres	keycloak-postgres	internal	Keycloak database
keycloak	keycloak	18080	SSO/authentication service
rabbitmq	rabbitmq	host network	Message queue
pma	pma	host network	Data helper service
alg-0	alg-0	8080	Palgo base algorithm service
sam-0	sam-0	4040	SAM algorithm service

esb/docker-compose.yml example:

x-alg-template: &alg-template
  image: docker.medipath.com.cn/alg:palgo
  restart: always
  network_mode: host
  runtime: nvidia
  mem_limit: 15G
  volumes:
    - /mnt:/mnt
    - ./cache:/root/.medipath
  healthcheck:
    test: [ "CMD", "bash", "-c", "curl -f http://127.0.0.1:$$API_PORT/health || exit 1", ]
    interval: 30s
    timeout: 10s
    retries: 6
    start_period: 10s

x-env-template: &env-template
  TZ: Asia/Shanghai
  MINIO_ENDPOINT: 127.0.0.1:9000
  NVIDIA_DRIVER_CAPABILITIES: all

services:
  minio-1:
    image: quay.io/minio/minio:RELEASE.2024-08-29T01-40-52Z
    hostname: minio-1
    container_name: minio-1
    restart: always
    command: server --console-address ":9001" http://minio-{1...1}/data{1...2}
    volumes:
      - /media/data1:/data1
      - /media/data2:/data2
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: ***
    expose:
      - 9000
      - 9001
    ports:
      - 9000:9000
      - 9001:9001
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:9000/minio/health/live" ]
      interval: 30s
      timeout: 20s
      retries: 3

  mongo:
    image: docker.medipath.com.cn/mongo
    container_name: mongo
    restart: always
    command: --quiet
    environment:
      TZ: Asia/Shanghai
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ***
    expose:
      - 27017
    ports:
      - 27017:27017
    volumes:
      - ./mongo/db:/data/db

  postgres:
    image: docker.medipath.com.cn/postgres:16
    container_name: keycloak-postgres
    restart: always
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password

  keycloak:
    image: docker.medipath.com.cn/keycloak
    container_name: keycloak
    restart: always
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ***
      KC_DB: postgres
      KC_DB_URL: "jdbc:postgresql://postgres:5432/keycloak"
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password
      KC_HTTP_ENABLED: true
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME: sso.local
    entrypoint: [ "/opt/keycloak/bin/kc.sh", "start" ]
    ports:
      - 18080:8080
    depends_on:
      - postgres

  rabbitmq:
    image: docker.medipath.com.cn/rabbitmq
    container_name: rabbitmq
    restart: always
    network_mode: host
    volumes:
      - ./mq:/var/lib/rabbitmq/mnesia
      - ./alg.mq:/etc/rabbitmq/conf.d/99-alg.conf
    environment:
      - RABBITMQ_DEFAULT_USER=admin
      - RABBITMQ_DEFAULT_PASS=***

  pma:
    image: docker.medipath.com.cn/pma
    container_name: pma
    restart: always
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /mnt:/mnt

  alg-0:
    <<: *alg-template
    container_name: alg-0
    environment:
      <<: *env-template
      API_PORT: 8080
      NVIDIA_VISIBLE_DEVICES: "0"
    volumes:
      - /mnt:/mnt

  sam-0:
    <<: *alg-template
    image: docker.medipath.com.cn/alg:sam
    container_name: sam-0
    environment:
      <<: *env-template
      API_PORT: 4040
      NVIDIA_VISIBLE_DEVICES: "0"
    volumes:
      - /mnt:/mnt

Start prerequisite services:

cd esb
docker compose up -d
docker compose ps

Prerequisite checks:

curl -f http://127.0.0.1:9000/minio/health/live
curl -f http://127.0.0.1:8080/health
curl -f http://127.0.0.1:4040/health
docker ps
ss -lntp

If alg-0 or sam-0 health checks fail, check GPU and NVIDIA container runtime before starting Palgo.

4. docker-compose.yml Example

services:
  train-service:
    image: docker.medipath.com.cn/palgo/train-service
    container_name: train-service
    restart: always
    privileged: true
    pid: host
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 59999
      PALGO_TRAIN_DIR: /mnt/data/palgo/train
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./log:/log
      - /mnt:/mnt

  alg-service:
    image: docker.medipath.com.cn/palgo/alg-service
    container_name: palgo-alg
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 58888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  search-service:
    image: docker.medipath.com.cn/palgo/search-service
    container_name: search-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 48888
    volumes:
      - ./log:/log
      - /mnt:/mnt
      - ./lucene:/lucene

  backend-service:
    image: docker.medipath.com.cn/palgo/backend-service
    container_name: backend-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 18888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  tenant-service:
    image: docker.medipath.com.cn/palgo/tenant-service
    container_name: tenant-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 28888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  project-service:
    image: docker.medipath.com.cn/palgo/project-service
    container_name: project-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 38888
    volumes:
      - ./log:/log
      - /mnt:/mnt

  case-service:
    image: docker.medipath.com.cn/case-service
    container_name: case-service
    restart: always
    network_mode: host
    env_file:
      - .env
    environment:
      TZ: Asia/Shanghai
      IXTF_API_PORT: 18082
    volumes:
      - ./log:/log
      - /mnt:/mnt

5. Server Requirements

Item	Requirement
OS	Ubuntu Server 22.04/24.04
CPU	8 cores or above
Memory	32 GB or above; 64 GB or above recommended for training
GPU	NVIDIA GPU is required for training and algorithm scenarios
Disk	1 TB or above data disk recommended
Time zone	Asia/Shanghai

Required:

• Docker
• Docker Compose plugin
• curl
• pigz, for offline image import/export
• NVIDIA Driver and NVIDIA Container Toolkit when GPU is needed

Pre-deployment checks:

docker version
docker compose version
nvidia-smi
docker ps

6. Port Plan

Port	Service	Description
18888	backend-service	Main backend service
28888	tenant-service	Tenant service
38888	project-service	Project service and Socket JS endpoint
48888	search-service	Search service
58888	alg-service	Palgo algorithm business service
59999	train-service	Training service
18082	case-service	Case service
9000	MinIO	esb prerequisite service
9001	MinIO Console	esb prerequisite service
27017	MongoDB	esb prerequisite service
18080	Keycloak	esb prerequisite service
8080	Base algorithm service alg-0	esb prerequisite service
4040	SAM service sam-0	esb prerequisite service

Expose only a unified reverse proxy port or HTTPS publicly. MongoDB, MinIO, RabbitMQ, training service, and algorithm service should not be exposed publicly.

7. Directory Plan

Create local directories in the Palgo deployment directory:

mkdir -p log lucene

Training directory:

sudo mkdir -p /mnt/data/palgo/train
sudo chown -R "$USER":"$USER" /mnt/data/palgo/train

Mounts:

Mount	Description
./log:/log	Log directory for all Palgo application services
/mnt:/mnt	Shared data directory
./lucene:/lucene	Search index directory
/var/run/docker.sock:/var/run/docker.sock	Train service access to host Docker

Note: train-service uses privileged: true, pid: host, and mounts the Docker socket. Deploy it only on trusted servers.

8. .env Configuration

Enter the Palgo deployment directory and edit:

vi .env

Example:

MP_SDK_MARKET_BIND_TENANT_CODE=67d92caa22d9ed0dc78bd002

PALGO_OSS_ENDPOINT=http://127.0.0.1:9000
PALGO_OSS_ACCESS_KEY=minio
PALGO_OSS_SECRET_KEY=***

PALGO_MQ_HOST=127.0.0.1
PALGO_MQ_USER=admin
PALGO_MQ_PASSWORD=***

PALGO_MONGO_URI=mongodb://root:***@127.0.0.1

PALGO_ALG_ENDPOINTS=http://127.0.0.1:8080
PALGO_SOCKET_JS_ENDPOINT=http://127.0.0.1:38888
PALGO_SEARCH_ENDPOINT=http://127.0.0.1:48888
PALGO_TRAIN_ENDPOINT=http://127.0.0.1:59999
PALGO_TRAIN_GPUS_START_IDX=1

CASE_MQ_HOST=127.0.0.1
CASE_MQ_USER=admin
CASE_MQ_PASSWORD=***
CASE_MONGO_URI=mongodb://root:***@127.0.0.1

Configuration:

Key	Description
MP_SDK_MARKET_BIND_TENANT_CODE	Bound tenant code
PALGO_OSS_*	MinIO/object storage configuration
PALGO_MQ_*	Palgo message queue configuration
PALGO_MONGO_URI	Palgo MongoDB URI
PALGO_ALG_ENDPOINTS	Base algorithm service endpoint
PALGO_SOCKET_JS_ENDPOINT	Project service Socket endpoint
PALGO_SEARCH_ENDPOINT	Search service endpoint
PALGO_TRAIN_ENDPOINT	Training service endpoint
PALGO_TRAIN_GPUS_START_IDX	Start GPU index for training tasks
CASE_*	Case service dependency configuration

Replace default passwords with secure site-specific passwords in production.

9. Image Preparation

Online:

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

Offline:

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

Use the actual image package name delivered on site.

10. Start and Check

Start prerequisite services:

cd esb
docker compose up -d
docker compose ps

Start Palgo application services:

cd ../palgo
docker compose up -d

Check Palgo containers:

docker compose ps
docker ps

Check ports:

ss -lntp

If the current version provides /health endpoints, run:

curl -f http://127.0.0.1:18888/health
curl -f http://127.0.0.1:28888/health
curl -f http://127.0.0.1:38888/health
curl -f http://127.0.0.1:48888/health
curl -f http://127.0.0.1:58888/health
curl -f http://127.0.0.1:59999/health
curl -f http://127.0.0.1:18082/health

If a service has no /health endpoint, use running container status, listening port, and logs without continuous errors as the acceptance criteria.

11. Business Acceptance

1. Open the Palgo system URL or proxy URL.
2. Log in with a test account.
3. Create or open tenant, project, and case data.
4. Upload or select test data files.
5. Run one algorithm analysis.
6. Run one search or view search results.
7. If training is enabled, submit one training task and verify status changes.
8. Confirm logs do not show continuous errors.

12. Common Operations Commands

docker compose ps
docker compose logs -f --tail=200 backend-service
docker compose logs -f --tail=200 tenant-service
docker compose logs -f --tail=200 project-service
docker compose logs -f --tail=200 search-service
docker compose logs -f --tail=200 alg-service
docker compose logs -f --tail=200 train-service
docker compose logs -f --tail=200 case-service
docker compose restart backend-service tenant-service project-service
docker compose restart search-service alg-service train-service case-service
docker compose down
docker compose pull
docker compose up -d
docker stats
nvidia-smi

13. Logs and Troubleshooting

File log directory:

./log

Container logs:

docker logs backend-service
docker logs tenant-service
docker logs project-service
docker logs search-service
docker logs palgo-alg
docker logs train-service
docker logs case-service

Search for:

ERROR
Exception
Connection refused
Mongo
RabbitMQ
MinIO
OSS
No such file
Permission denied
GPU
Docker socket

14. Update and Rollback

Backup before update:

cp .env .env.bak.$(date +%F)
cp docker-compose.yml docker-compose.yml.bak.$(date +%F)
tar -czf palgo-log-lucene-$(date +%F).tgz log lucene

Online update:

docker compose pull
docker compose up -d

Offline update:

pigz -dc palgo-update.tar.gz | docker load
docker compose up -d

Rollback:

1. Restore the previous .env and docker-compose.yml.
2. Confirm previous images exist locally.
3. Run:

docker compose up -d
docker compose ps

15. Backup Requirements

Item	Frequency
.env	Before every release
docker-compose.yml	Before every release
./lucene	Daily or before major upgrades
./log	As needed
/mnt/data/palgo/train	Based on training data importance
MongoDB data	Daily or before major upgrades
MinIO data	Daily or before major upgrades
RabbitMQ data	As needed

16. Common Troubleshooting

Issue	Common Cause	Action
Service exits immediately	Wrong .env configuration or unreachable dependency	Check corresponding docker logs and .env
Backend cannot access database	MongoDB not running, wrong credentials, network issue	Check PALGO_MONGO_URI and MongoDB status
Tasks cannot be delivered	RabbitMQ not running or wrong credentials	Check PALGO_MQ_* and CASE_MQ_*
File upload/read fails	MinIO configuration error or missing /mnt data	Check PALGO_OSS_* and /mnt mount
Algorithm returns no result	PALGO_ALG_ENDPOINTS unreachable or base algorithm container abnormal	Check algorithm service on 8080 and logs
Search abnormal	search-service abnormal or ./lucene permission issue	Check search-service logs and lucene permissions
Training task fails	Insufficient GPU, Docker socket unavailable, training directory permission issue	Check nvidia-smi, /var/run/docker.sock, and /mnt/data/palgo/train
Port conflict	Host network port already occupied	Use ss -lntp to find the process

17. Final Delivery Checklist

• [ ] Docker works.
• [ ] .env is configured for the site.
• [ ] The esb prerequisite service stack is running.
• [ ] MongoDB, MinIO, RabbitMQ, Keycloak, and base algorithm service are available.
• [ ] docker compose ps shows services running.
• [ ] Ports 18888/28888/38888/48888/58888/59999/18082 are listening.
• [ ] Login works.
• [ ] Project, case, and file access work.
• [ ] Algorithm analysis returns results.
• [ ] Search service works.
• [ ] If training is enabled, training tasks can be submitted and run.
• [ ] Logs do not show continuous errors.
• [ ] Configuration and key data are backed up.