开发环境

相关源文件

• .env.development
• .node-version
• .ruby-version

本文档提供了 Gumroad 代码库本地开发环境的设置和使用说明。它涵盖了先决条件、安装步骤、配置和应用程序的运行。有关 CI/CD 管道的详细信息，请参阅CI/CD 管道。

概述

Gumroad 开发环境使用 Docker 在不同平台提供一致的开发体验。开发堆栈包括：

• Ruby on Rails 作为主要的应用程序框架
• MySQL 用于数据库
• Redis 用于缓存和后台作业队列
• Elasticsearch 用于搜索功能
• Sidekiq 用于后台作业处理
• Webpack 用于 JavaScript 编译

下图展示了开发环境的主要组件：

来源: README.md47-59 README.md183-219

先决条件

在设置 Gumroad 开发环境之前，您需要安装几个依赖项

所需软件

依赖项	版本	备注
Ruby	.ruby-version 中的版本	核心语言
Node.js	最新 LTS	JavaScript 运行时
Docker 和 Docker Compose	最新版	容器运行时
MySQL	8.0.x	数据库客户端库
Percona Toolkit	最新版	数据库实用程序
ImageMagick	最新版	图像处理
libvips	最新版	现代图像处理
FFmpeg	最新版	视频元数据提取
PDFtk	最新版	PDF 操作

下面是显示这些组件在开发环境中如何交互的依赖关系图

来源: README.md35-114

平台特定安装

macOS

对于 macOS 用户，建议使用 Homebrew 安装依赖项

Linux (Debian/Ubuntu)

对于 Linux 用户，请使用 apt

来源: README.md66-78 README.md90-101

安装

设置 Ruby 环境

1. 安装 bundler 和 Ruby gems

2. 安装 dotenv，某些控制台命令需要它

设置 Node.js 环境

1. 启用 corepack 管理 npm 版本

2. 安装 Node.js 依赖项

来源: README.md118-159

配置

环境变量

应用程序无需自定义凭据即可启动，但要使用 S3、Stripe 或 Resend 等服务，您需要配置环境变量

1. 复制示例环境文件

2. 根据需要编辑 .env 以添加您的自定义凭据。

本地开发用的 SSL 证书

要为本地开发启用 HTTPS

1. 安装 mkcert

2. 生成证书

来源: README.md164-182

运行应用程序

启动 Docker 服务

使用 Docker 启动所需服务

在 Linux 上，您可能需要使用 sudo 来访问端口

在后台运行 Docker 服务

设置数据库

启动应用程序

启动 Rails 服务器、JavaScript 构建系统和 Sidekiq worker

一切运行后，访问 https://gumroad.dev 即可访问应用程序。

来源: README.md183-219

开发工具

登录

您可以使用以下凭据登录

• 用户名: seller@gumroad.com
• 密码: password
• 双因素身份验证代码: 000000

Elasticsearch 索引

设置完成后，您需要对 Elasticsearch 进行索引，以避免 index_not_found_exception 错误

推送通知

发送推送通知

来源: README.md223-244

调试

控制台访问

Rake 任务

VS Code / Cursor 调试

对于 Visual Studio Code 或 Cursor 调试

1. 安装所需的扩展

   • Ruby 扩展
   • vscode-rdbg 扩展

2. 启动支持服务

3. 运行非 Rails 服务

4. 从 VS Code 的“运行 -> 启动调试”菜单中使用“运行 Rails 服务器”启动配置。

来源: README.md246-262 docs/debugging.md1-14

Apple Pay 测试

Apple Pay 已为以下域名启用：

• gumroad.dev
• discover.gumroad.dev
• creator.gumroad.dev

对于自定义域名，请将其添加到 Stripe Dashboard 或通过 Rails 控制台添加

来源: docs/apple_pay.md1-10

Helper 小部件

Helper 小部件协助 Gumroad 创作者解决问题。要在本地运行它

1. 配置 Helper Next.js 服务器以在端口 3010 上运行
2. 如果需要，更新 .env.development 文件中的 HELPER_WIDGET_HOST
3. 确保凭据中的 helper_widget_secret 与 Helper 使用的密钥匹配

来源: docs/helper_widget.md1-7

代码格式检查

代码库使用

• ESLint 用于 JavaScript
• Rubocop 用于 Ruby

设置 Git 钩子进行本地格式检查

对于 VS Code 用户，代码格式化已在设置中配置为对 JavaScript/TypeScript 文件使用 Prettier。

来源: README.md263-264 .vscode/settings.json1-18

CI/CD 流水线

Gumroad 代码库使用 GitHub Actions 进行测试，使用 Buildkite 进行部署

来源: .github/workflows/tests.yml1-489 .buildkite/pipeline.yml1-64

GitHub Actions

测试工作流程包括

1. 构建一个基础 Docker 镜像
2. 构建一个测试镜像
3. 在 15 个并行节点上运行快速测试
4. 在 45 个并行节点上运行慢速测试

测试使用 Knapsack Pro 在并行运行器之间动态分发测试。

Buildkite 管道

部署管道包括

1. 构建一个基础 Docker 镜像
2. 构建一个 web 镜像
3. 并行编译资产
4. 对于主分支，需要手动批准
5. 部署到生产环境

来源: .github/workflows/tests.yml184-264 .github/workflows/tests.yml266-407 .buildkite/pipeline.yml1-64

常见开发任务

以下是常见开发任务的快速参考

任务	命令
启动服务	make local
启动应用程序	bin/dev
Rails 控制台	bin/rails c
数据库设置	bin/rails db:prepare
运行测试	bin/rails test
重新索引 Elasticsearch	DevTools.delete_all_indices_and_reindex_all (在 rails 控制台中)
格式化代码	ESLint 用于 JS，Rubocop 用于 Ruby
生成 SSL 证书	bin/generate_ssl_certificates

来源: README.md246-262 README.md223-244