DesignSafe-CI Portal Docker镜像文档

镜像概述和主要用途

本镜像为DesignSafe-CI Portal提供Docker化部署支持，旨在通过Docker和Docker Compose简化门户应用的部署、开发和测试流程。该门户支持Agave API集成、用户认证、数据管理等核心功能，适用于开发环境的本地部署和测试场景。

前置条件

运行DesignSafe-CI Portal需使用Docker和Docker Compose，需预先在目标系统安装以下工具：

• 安装Docker
• 安装Docker Compose

注意：Mac或Windows用户推荐安装Docker Toolbox，该工具会同时安装Docker、Docker Compose及Docker Machine（在Mac/Windows主机运行Docker必需）。

核心功能和特性

• Docker化部署：支持通过Docker Compose一键构建和启动多容器应用
• 环境配置：通过环境变量文件灵活配置应用参数（如调试模式、密钥、API集成等）
• 数据库管理：支持Django数据库迁移和超级用户创建
• API集成：支持Agave API集成（认证等功能）、TAS（管理后台访问）和RT（工单系统）
• 数据迁移：支持从生产环境导入数据到本地开发实例
• 证书管理：提供本地CA安装、自签名证书创建和管理工具
• 开发支持：支持自定义Django应用开发、CSS样式定制及测试（Django测试和前端测试）

使用场景和适用范围

• 开发环境：供开发人员在本地搭建门户应用进行功能开发和测试
• 测试环境：用于验证新功能、配置变更及数据迁移效果
• 演示环境：快速部署门户应用展示核心功能

详细使用方法和配置说明

首次设置

1. 克隆仓库

$ git clone [***]
$ cd portal

2. 构建容器

$ docker-compose build

3. 配置环境变量

复制环境变量示例文件并修改为自定义配置：

$ cp designsafe.env.sample designsafe.env

必填环境变量：

• DJANGO_DEBUG：开发环境设为True
• DJANGO_SECRET：生产环境需修改为自定义密钥
• TAS_*：配置后启用django.contrib.admin直接访问
• AGAVE_*：配置后启用Agave API集成（认证等）
• RT_*：配置后启用工单系统

4. 设置本地/测试数据库

# 启动容器
$ docker-compose up -d
# 进入Django容器
$ docker exec -it portal_django_1 bash
# 数据库迁移
# ./manage.py migrate
# 创建超级用户
# ./manage.py createsuperuser

5. 访问门户

• 本地主机：在浏览器中访问 http://localhost:8000
• Mac/Windows（Docker Machine）：需使用Docker Machine VM的IP，通过以下命令获取：

$ docker-machine ip default  # "default"为虚拟机名称
192.168.99.100  # 示例输出，访问 [***]

后续步骤

安装本地CA

证书文件位于conf/nginx/certs目录下，根据操作系统执行以下步骤：

OSX

1. 打开「钥匙串访问」应用
2. 选择「文件 > 导入项目」
3. 导航至$PROJECT/conf/nginx/certs目录，选择ca.pem
4. 搜索"designsafe"，双击「Designsafe CA」证书
5. 点击「信任」，选择「始终信任」
6. 关闭窗口保存设置

Linux

$ cd $PROJECT/conf/nginx/certs
$ sudo mkdir /usr/local/share/ca-certificates/extra
$ sudo cp ca.pem /usr/local/share/ca-certificates/extra/designsafeCA.pem
$ sudo update-ca-certificates

Firefox UI

1. 打开Firefox偏好设置
2. 搜索「证书」，点击「查看证书」
3. 在「证书管理器」中切换至「证书机构」标签
4. 点击「导入」，导航至$PROJECT/conf/nginx/certs，选择ca.pem

Firefox CLI（未测试）

$ sudo apt-get install libnss3-tools  # 或使用对应系统的包管理器
$ certutil -A -n "designsafeCA" -t "TCu,Cu,Tu" -i ca.pem -d ${DBDIR}

注：${DBDIR}因浏览器而异，详情参考：

• Chromium: Linux证书管理
• Firefox: 配置文件位置

创建本地CA和签名证书

1. 生成CA的RSA-2048密钥（仓库中已包含）：

   $ openssl genrsa -des3 -out ca.key 2048
   

2. 生成根CA证书（有效期365天）：

   $ openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.pem
   

   所有表单值建议设为"Designsafe CA"

3. 生成网站RSA-2048密钥（仓库中已包含）：

   $ openssl genrsa -out designsafe.dev.key 2048
   

4. 生成证书签名请求（CSR）：

   $ openssl req -new -key designsafe.dev.key -out designsafe.dev.csr
   

   所有表单值建议设为"Designsafe CA"

5. 确保designsafe.dev.ext配置正确，生成网站证书：

   $ openssl x509 -req -in designsafe.dev.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out designsafe.dev.crt -days 365 -sha256 -extfile designsafe.dev.ext
   

生成的文件包括：

• designsafe.dev.key（网站私钥）
• designsafe.dev.csr（网站证书签名请求）
• designsafe.dev.crt（网站证书）
• ca.key（CA私钥）
• ca.pem（CA证书）

从生产环境导入数据

如需将生产环境数据导入本地SQLite开发实例，需先使用Django的dumpdata命令创建datadump.json文件。

从生产数据库导出数据

使用生产环境配置文件导出数据：

$ docker run -it --rm -v $(pwd):/datadump \
    --env-file /path/to/production/designsafe.env \
    designsafeci/portal:latest bin/dumpdata.sh

该命令会在当前目录生成datadump-YYYYMMDD.json文件。

警告：请勿使用生产配置执行以下命令，会破坏数据库！

导入数据到本地实例

使用本地环境配置文件导入数据：

$ docker run -it --rm -v $(pwd):/datadump \
    --env-file /path/to/local/designsafe.env \
    designsafeci/portal:latest bin/loaddata.sh

导入成功后，当前目录会生成包含数据的SQLite数据库文件db.sqlite3。

更多详情参见Wiki页面

重新创建自签名证书

配置文件conf/nginx/designsafe.dev.conf已包含必要配置，执行以下命令创建自签名证书：

$ openssl req -config conf/nginx/designsafe.dev.conf -new -sha256 -newkey rsa:2048 -nodes -keyout conf/nginx/designsafe.dev.key -x509 -days 365 -out designsafe.dev.crt

开发DesignSafe-CI Portal

自定义应用（Apps）

DesignSafe自定义应用应放置于designsafe/apps目录，在Django的settings.py中通过designsafe.apps.{app_name}启用。

CSS/样式

样式参考和自定义CSS文档见DesignSafe样式参考。

测试

Django测试

Django测试需遵循Django测试规范，可通过以下命令在容器中运行：

$ docker run -it --rm portal_django python manage.py test --settings=designsafe.test_settings

前端测试

前端测试使用Jasmine框架和Karma引擎，测试指南见AngularJS单元测试开发指南。确保所有脚本和测试脚本在karma-conf.js中配置，运行命令：

$ docker run -it --rm portal_django bin/run-tests.sh

开发环境设置

使用docker-compose启动开发环境，默认配置文件docker-compose.yml以开发模式运行Django主服务，并包含Redis服务（用于WebSocket支持），可选择启用EF站点进行测试。

基本开发配置（HTTP）

$ docker-compose build
$ docker-compose up

Agave客户端回调URL需设为：[***]

HTTPS配置（需Nginx代理）

如需HTTPS支持（如Bo***集成），使用docker-compose-http.yml配置（包含Nginx代理和自签名证书）：

$ docker-compose -f docker-compose-http.yml build
$ docker-compose -f docker-compose-http.yml up

Agave客户端回调URL需设为：[***]

Agave文件系统设置

1. 删除旧元数据对象：

   $ metadata-list Q '{"name": "designsafe metadata"}' | while read x; do metadata-delete $x; done;
   

2. 运行walker.py创建文件系统元数据对象：

   $ python portal/dsapi/agave/tools/bin/walker.py <command> <api_server> <token> <systemId> <base_folder>
   

   • base_folder：通常设为用户名（修复主目录下所有文件）
   • command选项：
     • files：遍历文件并打印路径
     • meta：以文件系统方式遍历元数据对象并打印路径
     • files-fix：检查每个文件是否有对应元数据对象，无则创建
     • meta-fix：检查每个元数据对象是否有对应文件，无则删除

生产环境设置

生产环境部署由Ansible管理，详情参见ansible仓库。

Docker部署示例

Docker Compose构建命令

$ docker-compose build

启动容器并设置数据库

$ docker-compose up -d
$ docker exec -it portal_django_1 bash
# ./manage.py migrate
# ./manage.py createsuperuser

重新创建自签名证书命令

$ openssl req -config conf/nginx/designsafe.dev.conf -new -sha256 -newkey rsa:2048 -nodes -keyout conf/nginx/designsafe.dev.key -x509 -days 365 -out designsafe.dev.crt

环境变量配置说明

主要环境变量文件为designsafe.env（从designsafe.env.sample复制而来），关键配置项如下：