Skip to content

Commit 8c89b56

Browse files
VuQuoc18VuQuoc18
committed
feat: add development environment configuration and documentation
1 parent c37593a commit 8c89b56

File tree

5 files changed

+393
-2
lines changed

5 files changed

+393
-2
lines changed

‎.env‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ FRONTEND_HOST=http://localhost:5173
1313
# Environment: local, staging, production
1414
ENVIRONMENT=local
1515

16-
PROJECT_NAME="Full Stack FastAPI Project"
17-
STACK_NAME=full-stack-fastapi-project
16+
PROJECT_NAME="Lesmee"
17+
STACK_NAME=lesmee
1818

1919
# Backend
2020
BACKEND_CORS_ORIGINS="http://localhost,http://localhost:5173,https://localhost,https://localhost:5173,http://localhost.tiangolo.com"

‎DEVELOPMENT-DEV.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# LesMee Development Environment
2+
3+
This guide covers how to set up and use the LesMee development environment using Docker Compose.
4+
5+
## Quick Start
6+
7+
### Prerequisites
8+
- Docker Desktop installed and running
9+
- Git
10+
11+
### Setup
12+
```bash
13+
# Clone the repository (if not already done)
14+
git clone <repository-url>
15+
cd lesmee-full
16+
17+
# Start the development environment
18+
docker-compose -f docker-compose.dev.yml --env-file .env.dev up --build -d
19+
```
20+
21+
### Access Services
22+
Once started, you can access:
23+
- **Frontend**: http://localhost:5173 (React/Vite with hot reload)
24+
- **Backend API**: http://localhost:8000 (FastAPI with auto-reload)
25+
- **API Documentation**: http://localhost:8000/docs (Swagger UI)
26+
- **Health Check**: http://localhost:8000/api/v1/utils/health-check/ (Database + Redis status)
27+
28+
## Services Overview
29+
30+
### Database (PostgreSQL)
31+
- **Port**: 5432
32+
- **Host**: localhost
33+
- **Database**: lesmee_dev
34+
- **Username**: postgres
35+
- **Password**: postgres123
36+
37+
Connect with your favorite PostgreSQL client (DBeaver, pgAdmin, TablePlus, etc.)
38+
39+
### Redis
40+
- **Port**: 6379
41+
- **Host**: localhost
42+
- **Password**: redis123
43+
44+
Use Redis CLI or Redis GUI tools like RedisInsight.
45+
46+
### Backend (FastAPI)
47+
- **Port**: 8000
48+
- **Auto-reload**: Enabled
49+
- **API Docs**: http://localhost:8000/docs
50+
- **Health Check**: http://localhost:8000/api/v1/utils/health-check/
51+
52+
### Frontend (React/Vite)
53+
- **Port**: 5173
54+
- **Hot Reload**: Enabled
55+
- **Dev Server**: Vite development server
56+
57+
## Development Workflow
58+
59+
### Making Changes
60+
1. **Backend**: Edit files in `./backend/` - changes trigger automatic reload
61+
2. **Frontend**: Edit files in `./frontend/` - changes trigger hot reload via Vite
62+
63+
### Environment Variables
64+
Edit `.env.dev` to customize development settings:
65+
- Database credentials
66+
- Redis configuration
67+
- Admin user credentials
68+
- CORS origins
69+
70+
### Database Management
71+
```bash
72+
# Access database container
73+
docker-compose -f docker-compose.dev.yml exec db psql -U postgres -d lesmee_dev
74+
75+
# Run migrations manually
76+
docker-compose -f docker-compose.dev.yml exec backend alembic upgrade head
77+
78+
# Create new migration
79+
docker-compose -f docker-compose.dev.yml exec backend alembic revision --autogenerate -m "description"
80+
```
81+
82+
### Redis Management
83+
```bash
84+
# Access Redis CLI
85+
docker-compose -f docker-compose.dev.yml exec redis redis-cli
86+
87+
# Authenticate with password
88+
AUTH redis123
89+
```
90+
91+
## Useful Commands
92+
93+
### Environment Management
94+
```bash
95+
# Start development environment
96+
./scripts/dev-start.sh
97+
98+
# Stop development environment
99+
./scripts/dev-stop.sh
100+
101+
# View logs for all services
102+
docker-compose -f docker-compose.dev.yml logs -f
103+
104+
# View logs for specific service
105+
docker-compose -f docker-compose.dev.yml logs -f backend
106+
docker-compose -f docker-compose.dev.yml logs -f frontend
107+
docker-compose -f docker-compose.dev.yml logs -f db
108+
docker-compose -f docker-compose.dev.yml logs -f redis
109+
```
110+
111+
### Container Management
112+
```bash
113+
# Rebuild specific service
114+
docker-compose -f docker-compose.dev.yml up --build -d backend
115+
116+
# Restart specific service
117+
docker-compose -f docker-compose.dev.yml restart backend
118+
119+
# Execute commands in containers
120+
docker-compose -f docker-compose.dev.yml exec backend bash
121+
docker-compose -f docker-compose.dev.yml exec frontend sh
122+
```
123+
124+
### Cleaning Up
125+
```bash
126+
# Stop and remove containers, networks, volumes
127+
docker-compose -f docker-compose.dev.yml down -v
128+
129+
# Remove all unused Docker resources
130+
docker system prune -a --volumes
131+
```
132+
133+
## Default Credentials
134+
135+
### Admin User
136+
- **Email**: [email protected]
137+
- **Password**: admin123
138+
139+
### Database
140+
- **Host**: localhost
141+
- **Port**: 5432
142+
- **Database**: lesmee_dev
143+
- **Username**: postgres
144+
- **Password**: postgres123
145+
146+
### Redis
147+
- **Host**: localhost
148+
- **Port**: 6379
149+
- **Password**: redis123
150+
151+
## Troubleshooting
152+
153+
### Port Conflicts
154+
If ports are already in use, modify them in `docker-compose.dev.yml`:
155+
```yaml
156+
ports:
157+
- "5433:5432" # PostgreSQL on 5433
158+
- "6380:6379" # Redis on 6380
159+
```
160+
161+
### Permission Issues
162+
If you encounter permission errors, ensure Docker has proper permissions and consider:
163+
```bash
164+
# Fix Docker permissions on Linux/Mac
165+
sudo chown -R $USER:$USER ./
166+
```
167+
168+
### Backend Build Issues
169+
If backend fails to start:
170+
1. Check logs: `docker-compose -f docker-compose.dev.yml logs backend`
171+
2. Ensure `.env.dev` exists and is correctly configured
172+
3. Try rebuilding: `docker-compose -f docker-compose.dev.yml up --build -d backend`
173+
174+
### Frontend Build Issues
175+
If frontend fails to start:
176+
1. Check logs: `docker-compose -f docker-compose.dev.yml logs frontend`
177+
2. Ensure node_modules volume is properly mounted
178+
3. Try rebuilding: `docker-compose -f docker-compose.dev.yml up --build -d frontend`
179+
180+
## Development Best Practices
181+
182+
1. **Use Version Control**: Commit changes frequently with descriptive messages
183+
2. **Environment Variables**: Keep sensitive data in `.env.dev`, don't commit it
184+
3. **Database Migrations**: Always create migrations for schema changes
185+
4. **Code Quality**: Use linters and formatters configured in the project
186+
5. **Testing**: Run tests before committing changes
187+
6. **Documentation**: Update this file when making architectural changes
188+
189+
## Production Deployment
190+
191+
For production deployment, use the main `docker-compose.yml` file with Traefik reverse proxy, not this development setup.
192+
193+
## Need Help?
194+
195+
- Check the logs for detailed error messages
196+
- Refer to the main project documentation
197+
- Open an issue in the project repository

‎backend/DEVELOPMENT.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Development Guide - Lesmee Backend
2+
3+
## Environment Setup
4+
5+
### Prerequisites
6+
- Python 3.11+
7+
- uv package manager
8+
9+
### Setup
10+
```bash
11+
# Clone and navigate to backend directory
12+
cd backend
13+
14+
# Install dependencies
15+
uv sync
16+
17+
# Activate virtual environment
18+
source .venv/bin/activate # Linux/Mac
19+
# or
20+
.venv\Scripts\activate # Windows
21+
```
22+
23+
## Running Tests
24+
25+
### IMPORTANT: Environment Issue Fixed
26+
We discovered a critical issue where tests fail when run with global Python (httpx 0.28+) instead of project environment (httpx 0.24.1).
27+
28+
### Correct ways to run tests
29+
30+
1. **Recommended: Use test script**
31+
```bash
32+
./scripts/run-tests.sh
33+
```
34+
35+
2. **Explicit venv usage**
36+
```bash
37+
.venv/bin/python -m pytest tests/
38+
```
39+
40+
3. **Activate environment first**
41+
```bash
42+
source .venv/bin/activate
43+
pytest tests/
44+
```
45+
46+
### What NOT to do
47+
```bash
48+
# ❌ DON'T - Uses global Python with incompatible httpx
49+
python -m pytest tests/
50+
pytest tests/
51+
```
52+
53+
## IDE Configuration
54+
55+
### VSCode
56+
- `.vscode/settings.json` is configured to use project interpreter
57+
- Ensure VSCode Python extension is installed
58+
- Reload VSCode after settings change
59+
60+
### PyCharm
61+
- Settings → Project → Python Interpreter
62+
- Select: `/path/to/backend/.venv/bin/python`
63+
64+
## Verification
65+
66+
Check environment before running tests:
67+
```bash
68+
.venv/bin/python -c "import httpx; print(f'httpx: {httpx.__version__}')"
69+
# Should output: httpx: 0.24.1
70+
```
71+
72+
## Troubleshooting
73+
74+
### Tests fail with "TypeError: Client.__init__() got an unexpected keyword argument 'app'"
75+
**Cause**: Running tests with global Python (httpx 0.28+) instead of project environment (httpx 0.24.1)
76+
77+
**Solution**:
78+
```bash
79+
# Fix dependencies
80+
uv sync
81+
82+
# Use correct test command
83+
./scripts/run-tests.sh
84+
```
85+
86+
### httpx version conflict
87+
```bash
88+
# Check versions
89+
.venv/bin/python -c "import httpx; print(httpx.__version__)" # Should be 0.24.1
90+
python -c "import httpx; print(httpx.__version__)" # Might be 0.28.x
91+
92+
# Fix: Use project environment
93+
source .venv/bin/activate
94+
```
95+
96+
## Development Workflow
97+
98+
1. Always activate virtual environment before development
99+
2. Use `./scripts/run-tests.sh` for running tests
100+
3. Commit changes from project environment
101+
4. Never use global Python for this project
102+
103+
## API Test Coverage
104+
105+
Current test status:
106+
- ✅ TestClient working (httpx 0.24.1)
107+
- ❌ Authentication fixture needs fixing (separate issue)
108+
- 68+ API route tests ready to run
109+
110+
## Root Cause Analysis
111+
112+
See detailed report: `plans/251119-from-system-to-dev-testclient-typerror-report.md`
113+
114+
**Summary**: httpx 0.28.0+ removed `app` parameter, breaking FastAPI TestClient. Project correctly uses httpx 0.24.1, but environment switching causes failures.

‎backend/scripts/run-tests.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/bin/bash
2+
3+
# Test Runner Script - Ensures correct environment usage
4+
# Usage: ./scripts/run-tests.sh [test-path]
5+
6+
set -e
7+
8+
echo "=== Lesmee Backend Test Runner ==="
9+
echo "Date: $(date)"
10+
echo
11+
12+
# Check if .venv exists
13+
if [ ! -d ".venv" ]; then
14+
echo "❌ Error: .venv directory not found!"
15+
echo "Please run: uv sync"
16+
exit 1
17+
fi
18+
19+
# Check if we're in the correct directory
20+
if [ ! -f "pyproject.toml" ]; then
21+
echo "❌ Error: Must run from backend directory (where pyproject.toml is located)"
22+
exit 1
23+
fi
24+
25+
# Verify httpx version in .venv
26+
HTTPX_VERSION=$(.venv/bin/python -c "import httpx; print(httpx.__version__)")
27+
echo "✅ Using httpx version: $HTTPX_VERSION"
28+
29+
# Check if httpx version is compatible
30+
if [[ "$HTTPX_VERSION" == "0.28"* ]]; then
31+
echo "❌ Error: Incompatible httpx version $HTTPX_VERSION detected!"
32+
echo "This version is incompatible with FastAPI TestClient"
33+
echo "Please run: uv sync to fix dependencies"
34+
exit 1
35+
fi
36+
37+
# Check FastAPI version
38+
FASTAPI_VERSION=$(.venv/bin/python -c "import fastapi; print(fastapi.__version__)")
39+
echo "✅ Using FastAPI version: $FASTAPI_VERSION"
40+
41+
echo
42+
echo "🚀 Running tests with project environment..."
43+
44+
# Run tests with the specified path or default to all tests
45+
if [ $# -eq 0 ]; then
46+
echo "Running all tests..."
47+
.venv/bin/python -m pytest tests/ -v
48+
else
49+
echo "Running tests: $@"
50+
.venv/bin/python -m pytest "$@" -v
51+
fi
52+
53+
echo
54+
echo "✅ Tests completed!"

0 commit comments

Comments
 (0)