Skip to content

Commit 48ed2f9

Browse files
Copilotsubmarcos
Copilot
and
submarcos
committed
Complete comprehensive .github/copilot-instructions.md with validated commands and network limitations
Co-authored-by: submarcos <[email protected]>
1 parent aa5d2e6 commit 48ed2f9

File tree

1 file changed

+280
-0
lines changed

1 file changed

+280
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Geotrek-admin Development Instructions
2+
3+
Geotrek-admin is a Django-based geospatial web application for managing trekking, outdoor tourism data and geographic information. It uses PostGIS for spatial data, Redis for caching, and provides both a web admin interface and comprehensive APIs.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Network Limitations - CRITICAL
10+
- **Docker build from source FAILS** due to firewall limitations preventing Python download from GitHub
11+
- Timeout occurs when downloading `cpython-3.10.18+20250828-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz`
12+
- Build fails after exactly ~2 minutes with "operation timed out" error
13+
- **WORKAROUND**: Use pre-built official images: `docker pull geotrekce/admin:latest`
14+
- **Do not attempt** `docker compose build` - it will fail after ~2 minutes with network timeout
15+
- **Alternative**: Use Ubuntu package installation method for full functionality
16+
17+
### Development Setup (Network-Limited Environment)
18+
Use these **validated commands** in order:
19+
20+
```bash
21+
# 1. Setup environment and permissions
22+
cp .env.dist .env
23+
mkdir -p var/{log,cache,media,static,tmp,conf}
24+
chmod -R 777 var
25+
echo "127.0.0.1 geotrek.local" | sudo tee -a /etc/hosts
26+
27+
# 2. Pull pre-built image and tag for local use
28+
docker pull geotrekce/admin:latest
29+
docker tag geotrekce/admin:latest geotrek:latest
30+
31+
# 3. Start services (supporting containers work fine)
32+
docker compose up postgres redis convertit screamshotter -d
33+
# Wait for postgres to be healthy (about 30 seconds)
34+
35+
# 4. Note: Full development environment setup currently blocked by network limitations
36+
# Web container cannot start properly due to missing development dependencies in production image
37+
```
38+
39+
**TIMING**: Service startup takes ~30-45 seconds. NEVER CANCEL during startup phase.
40+
41+
### Alternative Installation Methods
42+
For full functionality, use one of these alternatives:
43+
44+
1. **Ubuntu Package Installation** (Recommended for production-like setup):
45+
```bash
46+
# Follow instructions from docs/installation-and-configuration/installation.rst
47+
bash -c "$(curl -fsSL https://raw.githubusercontent.com/GeotrekCE/Geotrek-admin/master/tools/install.sh)"
48+
```
49+
50+
2. **Manual Dependencies Setup** (If Docker build works in your environment):
51+
```bash
52+
# Only try if network allows GitHub downloads
53+
docker compose build # Takes 5-10+ minutes, often fails
54+
docker compose run --rm web update.sh # Takes 2-5 minutes
55+
docker compose run --rm web load_data.sh # Takes 5-15 minutes
56+
```
57+
58+
## Testing
59+
60+
### Django Tests
61+
**CRITICAL TIMING**: Django tests take 15-30+ minutes. **NEVER CANCEL.** Set timeout to 45+ minutes minimum.
62+
63+
```bash
64+
# Full test suite with coverage (LONG RUNNING - 20-30 minutes)
65+
make coverage # NEVER CANCEL: Takes 20-30 minutes. Set timeout to 45+ minutes
66+
67+
# Specific test environments
68+
make test # NEVER CANCEL: Standard tests, ~15 minutes, set timeout to 30+ minutes
69+
make test_nds # NEVER CANCEL: Non-dynamic segmentation tests, ~15 minutes, set timeout to 30+ minutes
70+
make tests # NEVER CANCEL: Both test and test_nds, ~30 minutes, set timeout to 60+ minutes
71+
```
72+
73+
**Note**: Tests require fully built development environment, which may not work due to network limitations documented above.
74+
75+
### Code Quality (Requires Development Environment)
76+
```bash
77+
make quality # ❌ Currently fails: ruff not found in production image
78+
make lint # ❌ Currently fails: ruff not found in production image
79+
make format # ❌ Currently fails: ruff not found in production image
80+
```
81+
82+
**Note**: Quality commands require development environment with ruff installed. Use alternative installation method for full functionality.
83+
84+
### End-to-End Tests (Cypress)
85+
**CRITICAL**: Requires complete setup with loaded data. Takes 10-15 minutes. **NEVER CANCEL.**
86+
87+
```bash
88+
# Setup test data first (NEVER CANCEL each step)
89+
make load_data # NEVER CANCEL: ~5-10 minutes, set timeout to 20+ minutes
90+
make load_test_integration # NEVER CANCEL: ~2-5 minutes, set timeout to 15+ minutes
91+
92+
# Run Cypress tests (NEVER CANCEL)
93+
cd cypress
94+
npm ci # NEVER CANCEL: ~2-3 minutes first time, set timeout to 10+ minutes
95+
./node_modules/.bin/cypress run # NEVER CANCEL: ~5-10 minutes, set timeout to 20+ minutes
96+
```
97+
98+
**Warning**: These commands require working development environment setup.
99+
100+
## Key Development Commands
101+
102+
### Management Commands (After successful setup)
103+
```bash
104+
# Database operations
105+
docker compose run --rm web ./manage.py migrate
106+
docker compose run --rm web ./manage.py createsuperuser
107+
docker compose run --rm web ./manage.py collectstatic --clear --noinput
108+
109+
# Translations
110+
make messages # Extract translatable strings
111+
make compilemessages # Compile translations
112+
113+
# Dependencies (requires network access)
114+
make deps # Update all requirements files, ~2-3 minutes
115+
```
116+
117+
### Running the Application
118+
```bash
119+
# Development server (if working environment)
120+
docker compose up # Access at http://geotrek.local:8000
121+
# or
122+
make serve
123+
```
124+
125+
## Validation Scenarios
126+
127+
**Always test these workflows after making changes:**
128+
129+
### 1. Basic Django Functionality
130+
```bash
131+
# Verify Django starts without errors
132+
docker compose run --rm web ./manage.py check
133+
134+
# Test basic management commands
135+
docker compose run --rm web ./manage.py help
136+
```
137+
138+
### 2. Database Operations
139+
```bash
140+
# Test database connectivity
141+
docker compose run --rm web ./manage.py dbshell -c "SELECT version();"
142+
143+
# Verify migrations
144+
docker compose run --rm web ./manage.py showmigrations
145+
```
146+
147+
### 3. API Endpoint Testing
148+
```bash
149+
# Test API availability (if server running)
150+
curl -f http://geotrek.local:8000/api/settings.json
151+
```
152+
153+
## What Actually Works in Network-Limited Environments
154+
155+
### ✅ Verified Working Commands
156+
```bash
157+
# Service management
158+
docker compose up postgres redis convertit screamshotter -d
159+
docker compose down
160+
docker compose ps
161+
162+
# Image management
163+
docker pull geotrekce/admin:latest
164+
docker tag geotrekce/admin:latest geotrek:latest
165+
166+
# File system operations
167+
cp .env.dist .env
168+
mkdir -p var/{log,cache,media,static,tmp,conf}
169+
chmod -R 777 var
170+
171+
# Basic validation
172+
curl -I https://raw.githubusercontent.com/GeotrekCE/Geotrek-admin/master/tools/install.sh
173+
```
174+
175+
### ❌ Known Failing Commands
176+
```bash
177+
# Development environment setup
178+
docker compose build # Network timeout
179+
docker compose run --rm web update.sh # Missing dependencies
180+
make test # Requires dev environment
181+
make lint # Missing ruff in production image
182+
```
183+
184+
### 🔄 Recommended Workflow for Coding Agents
185+
186+
1. **Always start with what works**: Pull official images and set up supporting services
187+
2. **Document network limitations** clearly in any changes
188+
3. **Use Ubuntu package installation** for full development environment
189+
4. **Focus on file-based changes** that don't require running the full application
190+
5. **Test with alternative installation methods** when full validation is needed
191+
192+
## Verified Command Timings
193+
194+
**Based on actual testing - use these timeout values:**
195+
196+
| Command | Duration | Recommended Timeout | Status |
197+
|---------|----------|-------------------|---------|
198+
| `docker compose build` | ~2 minutes | ❌ FAILS | Network timeout |
199+
| `docker compose up postgres` | ~30 seconds | 120 seconds | ✅ Works |
200+
| `docker pull geotrekce/admin:latest` | ~2-3 minutes | 600 seconds | ✅ Works |
201+
| `make quality` | ~30 seconds | 120 seconds | ❌ Missing ruff |
202+
| `make lint` | ~15 seconds | 60 seconds | ❌ Missing ruff |
203+
| `make format` | ~10 seconds | 60 seconds | ❌ Missing ruff |
204+
| `make test` | ~15+ minutes | 1800+ seconds | ❌ Needs dev env |
205+
| `make coverage` | ~20-30 minutes | 2700+ seconds | ❌ Needs dev env |
206+
| Cypress tests | ~10-15 minutes | 1200+ seconds | ❌ Needs dev env |
207+
208+
**Key**: ✅ = Verified working, ❌ = Known to fail or missing dependencies
209+
210+
## Common Tasks
211+
212+
### Repository Structure
213+
```
214+
/home/runner/work/Geotrek-admin/Geotrek-admin/
215+
├── geotrek/ # Main Django application
216+
│ ├── settings/ # Django settings
217+
│ ├── api/ # REST API
218+
│ ├── trekking/ # Core trekking models
219+
│ ├── tourism/ # Tourism models
220+
│ └── ... # Other Django apps
221+
├── docker/ # Docker configuration
222+
├── docs/ # Sphinx documentation
223+
├── cypress/ # E2E tests
224+
├── requirements.txt # Python dependencies
225+
├── Makefile # Build shortcuts
226+
└── docker-compose.yml
227+
```
228+
229+
### Key Files to Monitor
230+
- `geotrek/settings/` - Django configuration
231+
- `requirements.txt` / `requirements-dev.txt` - Dependencies
232+
- `Makefile` - Build and test commands
233+
- `.env` - Environment configuration
234+
- `docker-compose.yml` - Service definitions
235+
236+
### Configuration Files
237+
- `ruff.toml` - Code quality configuration
238+
- `setup.py` - Package definition and dependencies
239+
- `.env.dist` - Environment template
240+
241+
## Troubleshooting
242+
243+
### Known Issues
244+
1. **Docker build fails**: Use pre-built images as documented above
245+
2. **Permission errors**: Ensure `var/` directory has proper permissions (777)
246+
3. **Network timeouts**: All downloads from GitHub may fail in restricted environments
247+
4. **Database connection**: Ensure PostgreSQL container is healthy before running commands
248+
249+
### Log Locations
250+
- Application logs: `var/log/`
251+
- Docker logs: `docker compose logs [service]`
252+
- Test results: Console output, Cypress videos in `cypress/videos/`
253+
254+
### Performance Notes
255+
- Database queries can be slow due to complex geometric operations
256+
- PDF generation requires proper domain setup (geotrek.local)
257+
- Map tiles and static files need proper permissions
258+
259+
## CI/CD Integration
260+
261+
The repository includes GitHub Actions workflows:
262+
- `.github/workflows/test.yml` - Comprehensive test matrix
263+
- `.github/workflows/lint.yml` - Code quality checks
264+
- `.github/workflows/doc.yml` - Documentation builds
265+
266+
**Always run** `make quality` before committing to match CI requirements.
267+
268+
## Required System Resources
269+
- 4+ CPU cores (for complex geometric operations)
270+
- 8+ GB RAM (PostGIS operations are memory-intensive)
271+
- 50+ GB disk space (including media files)
272+
- Docker with at least 4GB memory allocation
273+
274+
## Important Notes
275+
- **NEVER CANCEL** long-running operations (builds, tests) - they may take 30+ minutes
276+
- Always use timeout values of 45+ minutes for build operations
277+
- Always use timeout values of 30+ minutes for test operations
278+
- Always validate changes with both Django and Cypress tests when possible
279+
- Geographic operations are CPU-bound and take significant time
280+
- The application serves as the backend for Geotrek-rando (public website) and Geotrek-mobile apps

0 commit comments

Comments
 (0)