civisanalytics/civis-services-shiny

Civis Services Shiny

镜像概述和主要用途

Civis Services Shiny 提供一个Docker镜像，用于在Civis平台上支持R Shiny应用部署，同时包含一个可直接在Civis平台部署的演示Shiny应用。该镜像旨在简化Shiny应用的部署流程，提供标准化的运行环境，并支持本地开发与测试。

核心功能和特性

• 标准化部署环境：提供预配置的Docker镜像，确保Shiny应用在Civis平台上的一致性运行
• 灵活的文件结构：支持单文件（app.R）或双文件（server.R和ui.R）应用结构
• 本地开发支持：可本地构建和运行镜像，便于开发调试
• 版本控制：通过Docker标签控制R版本，确保环境可重现
• 模块化支持：推荐的目录结构支持大型应用的模块化开发与维护

使用场景和适用范围

适用于需要在Civis平台部署R Shiny应用的用户，包括数据分析师、数据科学家和开发人员。特别适合需要快速部署交互式数据可视化应用、内部业务工具或客户展示系统的场景。

使用方法和配置说明

快速入门：使用演示应用

1. 登录Civis平台
2. 从顶部导航栏点击"发布"
3. 在"服务"下点击"Shiny Demo"

以上步骤将创建指向本GitHub仓库的Shiny演示应用服务，应用就绪后可按照Civis服务部署指南进行部署。

若需自定义演示应用，可https://github.com/civisanalytics/civis-services-shiny/fork%EF%BC%8C%E6%BC%94%E7%A4%BA%E5%BA%94%E7%94%A8%E6%BA%90%E4%BB%A3%E7%A0%81%E4%BD%8D%E4%BA%8E%60app/%60%E7%9B%AE%E5%BD%95%E3%80%82%E5%A6%82%E9%9C%80%E4%BD%BF%E7%94%A8%E8%87%AA%E5%AE%9A%E4%B9%89Docker%E9%95%9C%E5%83%8F%EF%BC%8C%E5%8F%AF%E4%BF%AE%E6%94%B9%E4%BB%93%E5%BA%93%E4%B8%AD%E7%9A%84%60Dockerfile%60%E5%92%8C%60entrypoint.sh%60%EF%BC%8C%E5%B9%B6%E6%89%98%E7%AE%A1%E5%88%B0%E4%B8%AA%E4%BA%BADockerHub%E8%B4%A6%E6%88%B7%E3%80%82

构建和部署自定义Shiny应用

前提要求

1. 应用源代码需托管在GitHub仓库，且Civis平台用户账户有权访问该仓库
2. 应用需包含app.R文件，或同时包含server.R和ui.R文件
3. Docker镜像名称为civisanalytics/civis-services-shiny，标签需从https://hub.docker.com/repository/docker/civisanalytics/civis-services-shiny/tags%E9%80%89%E6%8B%A9%EF%BC%88%E6%A0%87%E7%AD%BE%E5%86%B3%E5%AE%9AR%E7%89%88%E6%9C%AC%EF%BC%89

部署步骤

1. 在Civis平台创建新服务：
   • 导航至顶部菜单栏 -> "发布" -> "服务" -> "Shiny Demo"
   • 或参考Civis服务部署文档
2. 配置服务参数：
   • 指定GitHub仓库URL、Git标签（或分支、提交哈希）
   • 若应用代码位于仓库子目录，需指定目录路径

推荐目录结构

基础结构

顶层目录
│    README.md
│    Dockerfile
│    app.R
│    global.R

高级/自定义结构

顶层目录
│    README.md
│    server.R
│    ui.R
│    global.R
|    install.R
│    DESCRIPTION
│    <额外脚本>.R
│    <模块>.R
└─── www
     │    <自定义JS>.js
     │    <自定义CSS>.css
     │    <图片>.gif

注：<>中的文件名因项目而异

文件结构说明

• README.md：项目描述及运行说明
• app.R：包含server和ui的单文件应用（若存在server.R和ui.R则不需要）
• server.R：服务器逻辑代码，最终需定义server函数
• ui.R：UI元素逻辑代码，最终需定义UI对象
• global.R：应用启动时运行的全局逻辑，用于共享ui.R和server.R的状态
• install.R：依赖安装脚本（可选，也可在global.R中安装依赖）
• DESCRIPTION：项目元数据，主要用于Showcase模式
• <额外脚本>.R：server.R中主服务器函数外的额外逻辑
• <模块>.R：可共享的模块代码，通常通过source("modules.R")在global.R中加载
• www/：存放网站资源（JavaScript、CSS、图片等）

本地使用Docker镜像

构建本地镜像

bash
docker build -t civis-services-shiny .

从DockerHub拉取镜像

bash
docker pull civisanalytics/civis-services-shiny:latest

• latest标签为最新构建版本，可替换为具体版本号（如1.0）以获取可重现环境

本地测试与Civis平台集成

1. 构建测试镜像：

   bash
   docker build -t civis-services-shiny:test .
   

2. 运行容器：

   bash
   docker run --rm -p 3838:3838 -e APP_DIR=/app -e CIVIS_API_KEY civis-services-shiny:test
   

   • -p 3838:3838：映射容器端口3838到本地
   • -e APP_DIR=/app：指定应用目录（容器内路径）
   • -e CIVIS_API_KEY：传递Civis API密钥（可选，用于初始化Civis API客户端）

3. 访问应用：

   • 本地访问：http://0.0.0.0:3838
   • Docker主机IP访问：<docker-host-ip>:3838（如Docker for Mac中通常为http://127.0.0.1:3838/）

贡献指南

详见CONTRIBUTING。修改代码后需构建测试容器验证：

bash
docker build -t civis-services-shiny:test .

并在变更日志中记录修改内容。

维护者说明

• 自动构建：合并到master分支的PR会自动构建为DockerHub的latest标签
• 版本发布：创建格式为vX.X.X（主版本.次版本.修订版本）的标签后，DockerHub会自动构建三个标签：major、major.minor和major.minor.micro
• 分支构建：分支会自动构建为dev-<分支名>标签

许可证

BSD-3，详见LICENSE.md。