如何快速搭建Lago开发环境：Docker Compose下的热重载终极指南

【免费下载链接】lago Open Source Metering and Usage Based Billing 项目地址: https://gitcode.com/GitHub_Trending/la/lago

Lago是一款开源的计量和基于使用量的计费解决方案（Open Source Metering and Usage Based Billing），本指南将帮助你通过Docker Compose快速搭建完整的Lago开发环境，实现代码热重载和高效开发工作流。

📋 准备工作：开发环境必备条件

在开始搭建Lago开发环境前，请确保你的系统已安装以下工具：

• Git：用于克隆代码仓库
• Docker：容器化运行环境
  • Docker for Ubuntu
  • Docker Desktop for macOS
• OpenSSL：用于生成TLS证书

安装OpenSSL的命令：

# Ubuntu/Debian
sudo apt update && sudo apt install openssl

# macOS
brew install openssl

🔄 第一步：克隆Lago代码仓库

使用以下命令克隆Lago项目仓库（包含子模块）：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/la/lago
cd lago

⚙️ 第二步：配置开发环境别名

为简化Docker Compose命令，建议创建lago别名。根据你的shell类型执行以下命令：

Bash用户：

echo "export LAGO_PATH=${PWD}" >> ~/.bashrc
echo 'alias lago="docker compose -f $LAGO_PATH/docker-compose.dev.yml"' >> ~/.bashrc
source ~/.bashrc

Zsh用户：

echo "export LAGO_PATH=${PWD}" >> ~/.zshrc
echo 'alias lago="docker compose -f $LAGO_PATH/docker-compose.dev.yml"' >> ~/.zshrc
source ~/.zshrc

🔒 第三步：配置Traefik和TLS证书

Lago使用Traefik管理TLS证书和服务路由，按以下步骤配置：

1. 安装mkcert证书工具：

brew install mkcert nss  # macOS用户
# Ubuntu用户可参考mkcert官方文档安装

2. 生成TLS证书：

mkcert -install
cd $LAGO_PATH/traefik
mkdir certs
cd certs
mkcert -cert-file lago.dev.pem -key-file lago.dev-key.pem lago.dev "*.lago.dev"

3. 添加本地域名到hosts文件：

sudo tee -a /etc/hosts <<EOF
# Lago local domains
127.0.0.1 traefik.lago.dev
127.0.0.1 api.lago.dev
127.0.0.1 app.lago.dev
127.0.0.1 pdf.lago.dev
127.0.0.1 license.lago.dev
127.0.0.1 mail.lago.dev
127.0.0.1 webhook.lago.dev
EOF

🛠️ 第四步：配置API环境

复制环境变量模板并创建必要文件：

cd $LAGO_PATH
cp ./api/.env.dist ./api/.env
touch ./api/config/master.key

🚀 第五步：启动Lago开发环境

启动基础依赖服务

首先启动数据库、缓存和中间件服务：

lago up -d --wait db redis traefik mailhog clickhouse webhook

启动核心应用服务

接着启动前端和API服务（支持热重载）：

lago up front api api-worker api-clock

现在你可以通过以下地址访问本地Lago应用：

• 管理界面：https://app.lago.dev
• API接口：https://api.lago.dev
• 邮件测试：https://mail.lago.dev
• Webhook测试：https://webhook.lago.dev

后台运行服务

如果需要在后台运行所有服务：

lago up -d --wait front api api-worker api-clock

🔄 实现热重载开发

Lago开发环境默认支持代码热重载，当你修改以下目录的代码时，相关服务会自动重启：

• API代码：api/
• 前端代码：front/
• 事件处理器：events-processor/

📊 Lago系统架构概览

Lago采用微服务架构设计，以下是系统组件间的交互关系：

Lago系统架构图

⚡ 常用开发命令

数据库操作

# 进入Rails控制台
lago exec api bundle exec rails console

# 运行数据库迁移
lago exec api bundle exec rails db:migrate

# 创建测试数据库
lago exec -e LAGO_DISABLE_SCHEMA_DUMP=true -e RAILS_ENV=test api bundle exec rails db:create db:migrate

运行测试

# 自动运行测试（文件变更时）
lago exec api bundle exec guard

# 手动运行测试
lago exec api bundle exec rspec
lago exec api bundle exec rspec spec/path/to/your_test.rb

代码 linting

# 运行Rubocop检查
lago exec api bundle exec rubocop

# 自动修复可修复的lint问题
lago exec api bundle exec rubocop -A

🔧 环境变量配置

Docker服务依赖.env.development.default文件中的环境变量。如需自定义，可创建.env.development文件覆盖默认值：

# 示例：禁用Clickhouse
echo "LAGO_CLICKHOUSE_ENABLED=false" >> .env.development

📌 开发小贴士

1. 子模块管理：Lago使用Git子模块管理API和前端代码，更新子模块：

git pull --recurse-submodules

2. 专用工作队列：如需启用特定工作队列（如事件处理）：

# 在.env.development中添加
echo "SIDEKIQ_EVENTS=true" >> .env.development

# 启动专用 worker
lago up -d api-events-worker

3. Redis哨兵模式：如需测试Redis高可用配置：

# 在.env.development中添加
echo "LAGO_REDIS_SIDEKIQ_SENTINELS=redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379" >> .env.development
echo "LAGO_REDIS_SIDEKIQ_MASTER_NAME=master" >> .env.development

# 启动哨兵服务
lago --profile redis-sentinel up -d

通过以上步骤，你已经成功搭建了Lago的本地开发环境。现在可以开始为这个开源计量和计费系统贡献代码了！更多详细文档请参考docs/目录下的官方文档。

【免费下载链接】lago Open Source Metering and Usage Based Billing 项目地址: https://gitcode.com/GitHub_Trending/la/lago