unillett/catima

CATIMA

镜像概述和主要用途

CATIMA是一个Web应用，用于通过定义文档的数据模式轻松快速地创建结构化文档的在线目录。每个文档由多个数据字段描述，代表特定对象，可创建多种不同类型的对象。文档内容用于建立不同对象间的链接，同时提供集成搜索功能和每种对象类型的列表视图。

对于某些应用场景，CATIMA可替代FileMaker等数据库，但不提供许多高级功能。其设计目标是定义文档结构后即可开箱即用，有意提供相对较少的个性化选项，但允许创建与目录内容一起的自定义内容页面。

核心功能和特性

• 灵活的数据模式定义：通过定义文档的数据模式，自定义结构化文档的字段和结构
• 结构化文档管理：支持创建多种类型的对象，每个对象通过数据字段描述
• 对象间链接：利用文档内容建立不同对象之间的关联关系
• 集成搜索：内置搜索功能，可快速查找不同文档
• 列表视图：为每种对象类型提供专门的列表展示
• 开箱即用：定义文档结构后无需复杂配置即可使用
• 自定义内容页面：支持创建与目录内容结合的自定义页面

使用场景和适用范围

适用于需要快速搭建简单在线数据库的场景，适合替代基础数据库功能，尤其适合不需要高级数据库特性但希望快速设置和使用的用户。例如：小型团队的文档管理、简单物品目录、结构化信息收集与展示等场景。

使用方法和配置说明

开发环境配置

前置条件

需安装https://docs.docker.com/engine/install/%E7%8E%AF%E5%A2%83%E3%80%82

环境文件配置

1. 复制并重命名环境变量示例文件：

   bash
   cp example.env .env
   

   默认值适用于本地开发，如有需要可修改。

2. 复制并重命名Docker Compose覆盖配置文件：

   bash
   cp docker-compose.override.yml.dev docker-compose.override.yml
   

   默认值适用于本地开发，如有需要可修改。

编辑hosts文件

将catima.lan指向Docker主机IP。

容器构建与启动

在项目根目录执行以下命令构建并启动所有容器：

bash
docker-compose up  # 如需后台运行并静默日志，添加-d参数

等待所有容器创建完成并就绪（Puma启动并监听连接），设置脚本会自动配置应用。Redis和Postgres的数据通过Docker命名卷持久化，可通过以下命令管理卷：

• 查看现有卷：docker volume ls
• 删除卷（如重置数据库）：docker volume rm volume_name

访问前端应用

通过以下链接访问主应用： [***]

默认管理员账号：

• 用户名：***
• 密码：admin123

MailHog邮件查看

通过以下链接访问邮件： [***]

或通过JSON格式查看邮件： [***]

部署环境配置

环境文件配置

1. 复制并重命名环境变量示例文件：

   bash
   cp example.env .env
   

   生产环境需修改默认值，默认配置不适用于生产环境。

2. 复制并重命名Docker Compose覆盖配置文件：

   bash
   cp docker-compose.override.yml.prod docker-compose.override.yml
   

   如有需要可修改，默认值适用于生产环境。

配置文件设置

复制并重命名以下配置文件：

bash
cp config/domains.example.yml config/domains.yml
cp config/geo_layers.example.yml config/geo_layers.yml
cp config/restricted_robots.example.yml config/restricted_robots.yml

可根据需求修改值，应用运行中修改后需重启容器。

容器启动

构建并启动生产环境容器：

bash
docker compose up -d

反向代理配置

配置反向代理，将URL映射到端口8989。

测试与API规范

• 运行完整测试套件：

  bash
  docker exec -it -e NO_COVERAGE=1 catima-app bin/rails test
  

• 运行单个测试（指定行号）：

  bash
  docker exec -it -e NO_COVERAGE=1 catima-app bin/rails test path/to/file:line_number
  

• 无覆盖率测试（提升性能）：在docker exec参数中添加-e NO_COVERAGE=1

• 查看集成测试运行：在docker exec参数中添加-e HEADLESS=0，然后通过以下方式访问：

  • VNC：vnc://catima.lan:5900，密码：secret
  • 浏览器：[***]"Sessions"，找到对应测试会话的相机图标打开VNC查看器

• 运行API请求规范并生成API文档：

  bash
  docker exec -it catima-app rails swag:run
  

  API文档未版本化，需在部署时添加到项目中。

Docker镜像标签规则

GitHub Actions工作流基于以下事件生成Docker镜像标签：

• 推送到development分支：

  • {service}-dev-latest
  • {service}-stage-latest
  • {service}-stage-<sha>-<timestamp>（不可变）

• 推送到master分支：

  • {service}-latest

• 推送Git标签：

  • {service}-vX.Y.Z（不可变）

每周定时任务：

• 创建更新的 staging 镜像：{service}-stage-<sha>-<timestamp>（不可变）
• 创建更新的生产候选镜像：{service}-vX.Y.Z-<sha>-<timestamp>（不可变）

错误跟踪

使用[***]

Helm图表

项目的Helm图表位于https://github.com/unil-lettres/k8s%E7%9A%84%60catima%60%E7%9B%AE%E5%BD%95%E4%B8%AD%E3%80%82