feat: unify environment scripts with start.sh
- Add unified start.sh script with subcommands (all/backend/frontend) - Add process management (--stop, --status) - Remove separate start_backend.sh and start_frontend.sh - Update setup_dev_env.sh with pre-flight checks and --cpu-only/--skip-db options - Update .env.example to remove sensitive data and add DIFY translation config - Add .pid/ to .gitignore for process management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
egg
@@ -0,0 +1,96 @@
|
||||
# Design: Unify Environment Scripts
|
||||
|
||||
## Context
|
||||
|
||||
Tool_OCR 是一個 OCR 處理系統，包含 FastAPI 後端和 React 前端。目前的環境設置和啟動流程分散在多個腳本中：
|
||||
|
||||
- `setup_dev_env.sh` (341 lines) - 完整的開發環境設置
|
||||
- `start_backend.sh` (60 lines) - 後端服務啟動
|
||||
- `start_frontend.sh` (41 lines) - 前端服務啟動
|
||||
- `download_fonts.sh` - 字體下載 (可選)
|
||||
|
||||
**Current Pain Points:**
|
||||
1. 需要開兩個終端分別啟動前後端
|
||||
2. 環境變數配置分散在多個 `.env` 文件中
|
||||
3. 缺少服務狀態檢查和優雅停止機制
|
||||
4. GPU 配置需要手動驗證
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 簡化開發環境設置流程
|
||||
- 統一前後端啟動為單一命令
|
||||
- 改善錯誤訊息和故障排除體驗
|
||||
- 確保跨平台兼容性 (Ubuntu, WSL2)
|
||||
|
||||
**Non-Goals:**
|
||||
- 容器化 (Docker) - 保留為未來提案
|
||||
- 生產環境部署腳本
|
||||
- 自動化測試環境設置
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Unified Startup Script Design
|
||||
|
||||
**Decision:** 使用單一 `start.sh` 腳本，支援多種模式
|
||||
|
||||
```bash
|
||||
# Usage examples:
|
||||
./start.sh # Start both backend and frontend
|
||||
./start.sh backend # Start only backend
|
||||
./start.sh frontend # Start only frontend
|
||||
./start.sh --stop # Stop all services
|
||||
./start.sh --status # Show service status
|
||||
```
|
||||
|
||||
**Rationale:** 保持簡單，使用 bash 內建功能管理子進程，不引入額外依賴如 PM2 或 supervisord。
|
||||
|
||||
### 2. Process Management
|
||||
|
||||
**Decision:** 使用 PID 文件追蹤進程，支援優雅停止
|
||||
|
||||
- PID files stored in `.pid/` directory (gitignored)
|
||||
- SIGTERM for graceful shutdown
|
||||
- Fallback to SIGKILL after timeout
|
||||
|
||||
### 3. Environment Variable Strategy
|
||||
|
||||
**Decision:** 保持分離的 `.env` 文件，但改善文檔
|
||||
|
||||
- Root `.env.local` - 共用配置 (database, API keys)
|
||||
- Frontend `.env.local` - 前端特定配置 (VITE_* variables)
|
||||
- `.env.example` files updated with all required variables
|
||||
|
||||
**Rationale:** 前端 Vite 需要 `VITE_` 前綴的變數，混合會造成困擾。
|
||||
|
||||
### 4. Package Dependencies
|
||||
|
||||
**Current State:**
|
||||
- Python: 77 packages in requirements.txt
|
||||
- Node.js: 17 dependencies + 15 devDependencies
|
||||
|
||||
**Key Dependencies to Audit:**
|
||||
- PaddlePaddle GPU vs CPU selection
|
||||
- Unused development tools
|
||||
- Duplicate functionality packages
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Breaking existing workflows | Keep old scripts as aliases |
|
||||
| Complex process management | Start simple, add features incrementally |
|
||||
| WSL2 compatibility issues | Test on clean WSL2 Ubuntu 22.04 |
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Create new `start.sh` alongside existing scripts
|
||||
2. Update documentation to recommend new script
|
||||
3. After validation, deprecate old scripts (keep for one release)
|
||||
4. Remove old scripts in future version
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should we add systemd service files for production?
|
||||
2. Should we include database migration in startup?
|
||||
3. Should we add health check retries before opening browser?
|
||||
@@ -0,0 +1,25 @@
|
||||
# Change: Unify Environment Setup and Startup Scripts
|
||||
|
||||
## Why
|
||||
|
||||
目前專案有多個獨立的腳本來設置環境和啟動服務，開發者需要執行多個命令才能完整啟動專案。這增加了入門門檻並可能導致配置不一致的問題。
|
||||
|
||||
Currently the project has multiple independent scripts for environment setup and service startup, requiring developers to run multiple commands to fully start the project. This increases the onboarding barrier and may lead to configuration inconsistencies.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Audit and update package lists**: Review and clean up `requirements.txt` and `frontend/package.json`
|
||||
- **Consolidate environment files**: Merge `.env` configuration across root and frontend directories
|
||||
- **Update setup script**: Improve `setup_dev_env.sh` with better error handling and dependency validation
|
||||
- **Create unified startup script**: Combine `start_backend.sh` and `start_frontend.sh` into a single `start.sh` with options
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected files:
|
||||
- `requirements.txt` - Python dependencies audit
|
||||
- `frontend/package.json` - Node.js dependencies audit
|
||||
- `setup_dev_env.sh` - Updated environment setup
|
||||
- `start_backend.sh` - Will be replaced by unified script
|
||||
- `start_frontend.sh` - Will be replaced by unified script
|
||||
- `start.sh` - New unified startup script
|
||||
- `.env*` files - Environment configuration cleanup
|
||||
@@ -0,0 +1,73 @@
|
||||
# Development Environment
|
||||
|
||||
This capability defines the development environment setup and service management for Tool_OCR.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Unified Service Startup
|
||||
|
||||
The system SHALL provide a single startup script that can launch all services or individual components.
|
||||
|
||||
#### Scenario: Start all services
|
||||
|
||||
- **WHEN** developer runs `./start.sh`
|
||||
- **THEN** both backend and frontend services start
|
||||
- **AND** service URLs are displayed
|
||||
|
||||
#### Scenario: Start only backend
|
||||
|
||||
- **WHEN** developer runs `./start.sh backend`
|
||||
- **THEN** only the backend service starts on port 8000
|
||||
|
||||
#### Scenario: Start only frontend
|
||||
|
||||
- **WHEN** developer runs `./start.sh frontend`
|
||||
- **THEN** only the frontend service starts on port 5173
|
||||
|
||||
### Requirement: Service Process Management
|
||||
|
||||
The system SHALL provide commands to check status and stop running services.
|
||||
|
||||
#### Scenario: Check service status
|
||||
|
||||
- **WHEN** developer runs `./start.sh --status`
|
||||
- **THEN** the script displays which services are running with their PIDs
|
||||
|
||||
#### Scenario: Stop all services
|
||||
|
||||
- **WHEN** developer runs `./start.sh --stop`
|
||||
- **THEN** all running services are gracefully terminated
|
||||
|
||||
### Requirement: Environment Setup Validation
|
||||
|
||||
The setup script SHALL validate that all required dependencies are correctly installed.
|
||||
|
||||
#### Scenario: Validate Python environment
|
||||
|
||||
- **WHEN** setup script runs
|
||||
- **THEN** Python version is checked (3.10+)
|
||||
- **AND** virtual environment is created or verified
|
||||
- **AND** all pip packages are installed
|
||||
|
||||
#### Scenario: Validate Node.js environment
|
||||
|
||||
- **WHEN** setup script runs
|
||||
- **THEN** Node.js LTS version is installed via nvm
|
||||
- **AND** npm dependencies are installed
|
||||
|
||||
#### Scenario: Validate GPU support (optional)
|
||||
|
||||
- **WHEN** setup script runs on a system with NVIDIA GPU
|
||||
- **THEN** CUDA version is detected
|
||||
- **AND** appropriate PaddlePaddle GPU version is installed
|
||||
- **AND** GPU availability is verified
|
||||
|
||||
### Requirement: Environment Configuration
|
||||
|
||||
The system SHALL use `.env.example` files to document all required environment variables.
|
||||
|
||||
#### Scenario: New developer setup
|
||||
|
||||
- **WHEN** developer clones the repository
|
||||
- **THEN** `.env.example` files document all required variables
|
||||
- **AND** developer copies to `.env.local` and fills in values
|
||||
@@ -0,0 +1,31 @@
|
||||
# Tasks: Unify Environment Scripts
|
||||
|
||||
## 1. Package Audit and Update
|
||||
- [x] 1.1 Review Python dependencies in `requirements.txt` for unused/outdated packages
|
||||
- [x] 1.2 Review Node.js dependencies in `frontend/package.json`
|
||||
- [x] 1.3 Document system-level dependencies (apt packages, nvm, pandoc, etc.)
|
||||
- [x] 1.4 Update `requirements.txt` with corrected versions and comments
|
||||
|
||||
## 2. Environment Configuration Cleanup
|
||||
- [x] 2.1 Audit `.env`, `.env.local`, `.env.example` files in root and frontend
|
||||
- [x] 2.2 Consolidate duplicate environment variables
|
||||
- [x] 2.3 Update `.env.example` with all required variables
|
||||
- [x] 2.4 Remove sensitive data from version control (if any)
|
||||
|
||||
## 3. Update Setup Script
|
||||
- [x] 3.1 Add pre-flight checks (disk space, memory, existing installations)
|
||||
- [x] 3.2 Improve error messages with solutions
|
||||
- [x] 3.3 Add optional component installation (e.g., skip GPU detection if not needed)
|
||||
- [x] 3.4 Add database initialization step to setup script
|
||||
- [ ] 3.5 Test setup on clean Ubuntu 22.04/WSL2 environment
|
||||
|
||||
## 4. Create Unified Startup Script
|
||||
- [x] 4.1 Create `start.sh` with subcommands (all/backend/frontend)
|
||||
- [x] 4.2 Add process management (start, stop, restart, status)
|
||||
- [x] 4.3 Add log output options (combined/separate)
|
||||
- [x] 4.4 Preserve individual scripts for backwards compatibility (optional) - Removed old scripts
|
||||
- [x] 4.5 Test unified script in development environment
|
||||
|
||||
## 5. Documentation
|
||||
- [ ] 5.1 Update README with new startup instructions (skipped per user request)
|
||||
- [ ] 5.2 Add troubleshooting section for common issues (skipped per user request)
|
||||
Reference in New Issue
Block a user