overture/song-server

Song 镜像文档

镜像概述和主要用途

Song 是一个包含微服务（song-server）和CLI客户端（song-client）的项目，两者均基于Java 8和Spring Boot开发。其核心用途是快速、可靠地跟踪分散在多个云存储系统中的基因组元数据，支持元数据的提交、管理、发布及相关操作，适用于基因组数据管理场景。

核心功能和特性

• 跨云存储元数据跟踪：统一管理分布在不同云存储系统的基因组元数据
• 完整的服务与客户端：提供song-server微服务和song-client CLI工具，支持服务端部署与客户端交互
• 灵活的开发模式：支持Docker化开发，提供开发模式（本地构建后容器运行，暴露调试端口）和演示模式（容器内构建，完全隔离环境）
• API文档支持：集成Swagger，提供API文档（运行时可访问http://localhost:8080/swagger-ui.html）
• 多配置方式：CLI客户端支持通过配置文件（application.yml）或环境变量配置，环境变量优先级更高

使用场景和适用范围

• 基因组数据管理：科研机构或生物信息团队用于跟踪、管理基因组数据元信息
• 多云存储环境：适用于元数据分散在多个云存储系统的场景
• 开发与测试：支持本地快速部署依赖服务，模拟生产环境进行开发和测试
• 元数据操作自动化：通过CLI客户端实现元数据提交、发布、清单生成等操作的自动化

使用方法和配置说明

构建项目

通过Maven构建项目，生成可执行JAR包：

bash
mvn clean package

本地运行

直接通过Maven运行

bash
git clone git@github.com:icgc-dcc/SONG.git
cd SONG/song-server
mvn spring-boot:run -Dspring-boot.run.profiles=dev,test

通过JAR包运行

bash
java -jar song-server-0.1.1-SNAPSHOT.jar --spring.profiles.active=dev,test

Docker化开发

提供make命令支持本地部署依赖服务，分为两种模式：

1. 开发模式（默认）

• 特点：本地构建（Docker主机执行mvn package）后将文件复制到容器运行，支持快速开发；暴露调试端口（song-client:5005，song-server:5006）
• 启用方式：DEMO_MODE=0（未定义时默认）

调试配置（IntelliJ）

• song-client调试：
  1. 创建Docker镜像运行配置（可通过make intellij-song-client-config获取基础配置）
  2. 创建远程调试配置：
     • Host: localhost，Port: 5005
     • Use module classpath: song-client
     • 配置前置步骤：启动Docker容器，添加延迟（如sleep 5）确保调试端口绑定
• song-server调试：
  1. 启动服务：make clean start-song-server
  2. 创建远程调试配置：
     • Host: localhost，Port: 5006
     • Use module classpath: song-server

运行song-client（开发模式）

bash
./docker/tools/song-client-dev ping  # 示例：ping song-server

2. 演示模式

• 特点：容器内构建（不依赖Docker主机Maven环境），环境完全隔离，但构建速度慢（需重复下载依赖）
• 启用方式：DEMO_MODE=1

启动song-server（演示模式）

bash
make start-song-server DEMO_MODE=1

运行song-client（演示模式）

bash
./docker/tools/song-client-demo ping  # 示例：ping song-server

API文档

服务运行时可通过Swagger UI访问API文档：

• 本地地址：http://localhost:8080/swagger-ui.html

Docker Song Client 使用说明

song-client是与song-server交互的CLI工具，支持Docker化运行。

配置方式

支持通过conf/application.yml文件或环境变量配置，环境变量优先级更高。配置项及对应环境变量如下：

配置示例（环境变量方式）：

bash
CLIENT_SERVER_URL=http://localhost:8080 \
CLIENT_STUDY_ID=ABC123-CA \
CLIENT_PROGRAM_NAME=sing \
CLIENT_DEBUG=true \
CLIENT_ACCESS_TOKEN=myAccessToken \
./bin/sing config  # 本地运行示例

Docker运行命令

基本运行

bash
docker run --rm \
  -e 'CLIENT_SERVER_URL=http://localhost:8080' \
  -e 'CLIENT_STUDY_ID=ABC123-CA' \
  -e 'CLIENT_PROGRAM_NAME=sing' \
  -e 'CLIENT_DEBUG=true' \
  -e 'CLIENT_ACCESS_TOKEN=myAccessToken' \
  overture/song-client:latest \
  sing config

非root用户运行

• 使用预定义song用户：

  bash
  docker run --rm \
    -u song \
    -e 'CLIENT_SERVER_URL=http://localhost:8080' \
    ...  # 其他环境变量
    overture/song-client:latest \
    sing config
  

• 使用主机用户（需确保挂载目录权限）：

  bash
  docker run --rm \
    -u $(id -u):$(id -g) \
    -e 'CLIENT_SERVER_URL=http://localhost:8080' \
    ...  # 其他环境变量
    overture/song-client:latest \
    sing config
  

输出文件到主机

通过挂载卷将容器内输出文件映射到主机，例如生成清单文件：

bash
mkdir -p ./mydir  # 确保主机目录存在且有权限
docker run --rm \
  -u $(id -u):$(id -g) \
  -v $PWD/mydir:/data \
  -e 'CLIENT_SERVER_URL=http://localhost:8080' \
  -e 'CLIENT_STUDY_ID=ABC123-CA' \
  -e 'CLIENT_PROGRAM_NAME=sing' \
  -e 'CLIENT_DEBUG=true' \
  -e 'CLIENT_ACCESS_TOKEN=myAccessToken' \
  overture/song-client:latest \
  sing manifest -a someAnalysisId -d /data -f /data/output-manifest.txt

生成的output-manifest.txt将保存到主机./mydir目录。

注意事项

• 启用安全配置文件时，需依赖OAuth2服务器。
• 开发模式下，确保本地已安装Maven，以便执行mvn package。
• 演示模式构建速度较慢，建议仅用于环境隔离测试。