Add Windows development support and cross-platform compatibility
- Remove Windows-incompatible files (:Zone.Identifier) - Add comprehensive Windows development guide - Update .gitignore to prevent future Windows compatibility issues - Add cross-platform support section to README - Enable development on Windows with deployment to Linux Fixes Windows git clone issues and enables hybrid development workflow
This commit is contained in:
parent
79f496df34
commit
c7132ae7d5
10
README.md
10
README.md
|
|
@ -21,6 +21,16 @@ A comprehensive web-based application for managing and executing Python scripts
|
|||
- Conda (for environment management)
|
||||
- Modern web browser with WebSocket support
|
||||
|
||||
### Cross-Platform Support
|
||||
|
||||
ScriptsManager supports development on both Windows and Linux:
|
||||
|
||||
- ✅ **Windows Development**: Use WSL2 or Docker Desktop for fast development
|
||||
- ✅ **Linux Production**: Deploy to Linux servers for optimal performance
|
||||
- ✅ **Cross-Platform Scripts**: Write scripts that work on both platforms
|
||||
|
||||
📖 **For Windows developers**: See [Windows Development Guide](WINDOWS-DEVELOPMENT-GUIDE.md) for detailed setup instructions and best practices.
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Clone or extract the project:**
|
||||
|
|
|
|||
|
|
@ -0,0 +1,291 @@
|
|||
# Windows Development Guide - ScriptsManager
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to set up a cross-platform development environment for ScriptsManager, allowing developers to work on Windows for fast development and deploy to Linux for production.
|
||||
|
||||
## Problem Solved
|
||||
|
||||
Previously, Windows users couldn't clone the repository due to files with characters that are invalid in Windows file systems (specifically `:Zone.Identifier` files). This has been resolved by:
|
||||
|
||||
1. ✅ Removing all problematic files with `:` characters
|
||||
2. ✅ Adding Windows-incompatible patterns to `.gitignore`
|
||||
3. ✅ Ensuring all file paths are compatible with both systems
|
||||
|
||||
## Windows Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Git for Windows** with WSL support (recommended)
|
||||
- **Docker Desktop** for Windows
|
||||
- **Python 3.11+** (optional, for local script development)
|
||||
- **VS Code** with Remote-WSL extension (recommended)
|
||||
|
||||
### Option 1: WSL2 Development (Recommended)
|
||||
|
||||
WSL2 provides the best compatibility with Linux deployment:
|
||||
|
||||
```bash
|
||||
# In WSL2 Ubuntu terminal
|
||||
git clone https://github.com/your-repo/scriptmanager.git
|
||||
cd scriptmanager
|
||||
|
||||
# Development with Docker
|
||||
./docker-manage.sh start
|
||||
|
||||
# Access at http://localhost:5003
|
||||
```
|
||||
|
||||
### Option 2: Native Windows Development
|
||||
|
||||
For Windows-native development (experimental):
|
||||
|
||||
```powershell
|
||||
# Clone repository
|
||||
git clone https://github.com/your-repo/scriptmanager.git
|
||||
cd scriptmanager
|
||||
|
||||
# Use Docker Desktop
|
||||
docker-compose --profile dev up -d
|
||||
|
||||
# Access at http://localhost:5003
|
||||
```
|
||||
|
||||
## File System Compatibility
|
||||
|
||||
### Resolved Issues
|
||||
|
||||
The following Windows-incompatible elements have been addressed:
|
||||
|
||||
- ❌ ~~Files with `:` characters (Zone.Identifier)~~
|
||||
- ❌ ~~Files with `<>|"*?` characters~~
|
||||
- ✅ Path lengths under Windows limits (260 chars)
|
||||
- ✅ Case-insensitive file naming conflicts
|
||||
|
||||
### .gitignore Protection
|
||||
|
||||
The following patterns are now ignored to prevent Windows compatibility issues:
|
||||
|
||||
```gitignore
|
||||
# Windows compatibility - files with problematic characters
|
||||
*:Zone.Identifier
|
||||
*:*
|
||||
desktop.ini
|
||||
Thumbs.db
|
||||
*.lnk
|
||||
```
|
||||
|
||||
## Cross-Platform Workflow
|
||||
|
||||
### Development Cycle
|
||||
|
||||
1. **Windows Development**:
|
||||
```bash
|
||||
# Fast development on Windows
|
||||
git clone <repo>
|
||||
cd scriptmanager
|
||||
|
||||
# Edit scripts in your preferred Windows editor
|
||||
# Test locally with Docker Desktop
|
||||
docker-compose --profile dev up -d
|
||||
```
|
||||
|
||||
2. **Linux Testing**:
|
||||
```bash
|
||||
# Before production deployment, test on Linux
|
||||
git push origin feature-branch
|
||||
|
||||
# On Linux server
|
||||
git pull origin feature-branch
|
||||
./docker-manage.sh start
|
||||
```
|
||||
|
||||
3. **Production Deployment**:
|
||||
```bash
|
||||
# Linux production environment
|
||||
git checkout main
|
||||
git pull origin main
|
||||
./docker-manage.sh start
|
||||
```
|
||||
|
||||
### Script Development
|
||||
|
||||
#### Windows Script Development
|
||||
|
||||
1. Create/edit scripts in `app/backend/script_groups/`
|
||||
2. Use relative paths for file operations
|
||||
3. Test with Windows line endings (CRLF) - will be auto-converted
|
||||
4. Avoid hardcoded Linux paths like `/tmp/`, use `tempfile` module
|
||||
|
||||
#### Cross-Platform Script Guidelines
|
||||
|
||||
```python
|
||||
# ✅ Good - Cross-platform
|
||||
import os
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
# Use pathlib for cross-platform paths
|
||||
script_dir = Path(__file__).parent
|
||||
data_file = script_dir / "data" / "config.json"
|
||||
|
||||
# Use tempfile for temporary files
|
||||
with tempfile.NamedTemporaryFile(suffix='.csv') as tmp:
|
||||
tmp_path = tmp.name
|
||||
|
||||
# ❌ Avoid - Linux-specific
|
||||
data_file = "/app/data/config.json" # Hardcoded Linux path
|
||||
tmp_file = "/tmp/temp.csv" # Linux-specific temp directory
|
||||
```
|
||||
|
||||
## Docker Considerations
|
||||
|
||||
### Windows Docker Desktop
|
||||
|
||||
- Ensure Linux containers mode is enabled
|
||||
- File sharing should be configured for your project directory
|
||||
- WSL2 backend provides better performance than Hyper-V
|
||||
|
||||
### Volume Mounts
|
||||
|
||||
Docker volume mounts work differently on Windows. The current `docker-compose.yml` is configured to work on both platforms:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./app:/app/app # Cross-platform relative path
|
||||
- ./data:/app/data # Works on both Windows and Linux
|
||||
- ./logs:/app/logs # Preserves logs across restarts
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Cross-Platform .env Configuration
|
||||
|
||||
Create platform-specific `.env` files if needed:
|
||||
|
||||
```bash
|
||||
# .env.windows (for Windows development)
|
||||
FLASK_ENV=development
|
||||
DEBUG=True
|
||||
DATABASE_URL=postgresql://user:pass@localhost:5432/db
|
||||
|
||||
# .env.linux (for Linux production)
|
||||
FLASK_ENV=production
|
||||
DEBUG=False
|
||||
DATABASE_URL=postgresql://user:pass@postgres:5432/db
|
||||
```
|
||||
|
||||
## Testing Across Platforms
|
||||
|
||||
### Before Git Push
|
||||
|
||||
Always test your changes work on both platforms:
|
||||
|
||||
```bash
|
||||
# Windows testing
|
||||
docker-compose --profile dev up -d
|
||||
curl http://localhost:5003/health
|
||||
|
||||
# Linux testing (in WSL or VM)
|
||||
./docker-manage.sh start
|
||||
curl http://localhost:5003/health
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
Consider setting up GitHub Actions for cross-platform testing:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/cross-platform-test.yml
|
||||
name: Cross-Platform Tests
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-latest, windows-latest]
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Test with Docker
|
||||
run: |
|
||||
docker-compose --profile dev up -d
|
||||
# Add your tests here
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Windows Issues
|
||||
|
||||
1. **Line Ending Issues**:
|
||||
```bash
|
||||
# Configure Git to handle line endings
|
||||
git config --global core.autocrlf true
|
||||
```
|
||||
|
||||
2. **Path Length Limitations**:
|
||||
```bash
|
||||
# Enable long paths on Windows 10+
|
||||
git config --global core.longpaths true
|
||||
```
|
||||
|
||||
3. **File Permission Issues**:
|
||||
```bash
|
||||
# In WSL, fix file permissions
|
||||
chmod +x docker-manage.sh
|
||||
chmod +x *.sh
|
||||
```
|
||||
|
||||
4. **Docker Volume Issues**:
|
||||
- Ensure Docker Desktop file sharing includes your project directory
|
||||
- Try restarting Docker Desktop if volumes aren't mounting
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- Use WSL2 for better file system performance
|
||||
- Consider moving large datasets outside the synced folders
|
||||
- Use `.dockerignore` to exclude unnecessary files from builds
|
||||
|
||||
## Scripts Manager Specific Notes
|
||||
|
||||
### Script Groups
|
||||
|
||||
When developing new script groups on Windows:
|
||||
|
||||
1. Create the script in `app/backend/script_groups/your_group/`
|
||||
2. Use relative imports and paths
|
||||
3. Test the proxy system with `http://localhost:5003/project/X/script/Y/user/Z/`
|
||||
4. Ensure metadata.json is properly formatted
|
||||
|
||||
### Database
|
||||
|
||||
The PostgreSQL database runs in Docker and is consistent across platforms. No special Windows considerations needed.
|
||||
|
||||
### Proxy System
|
||||
|
||||
The internal proxy system works the same on both platforms, routing from port 5003 to internal script ports (5200+).
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. ✅ **Always develop in WSL2 when possible** for maximum Linux compatibility
|
||||
2. ✅ **Use pathlib and relative paths** in your scripts
|
||||
3. ✅ **Test on both platforms** before committing
|
||||
4. ✅ **Use Docker for consistent environments**
|
||||
5. ✅ **Keep file names simple** - avoid special characters
|
||||
6. ✅ **Configure Git properly** for line endings and long paths
|
||||
7. ✅ **Use environment variables** for platform-specific configuration
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues with Windows development:
|
||||
|
||||
1. Check this guide first
|
||||
2. Verify your Docker Desktop configuration
|
||||
3. Try WSL2 if using native Windows
|
||||
4. Check GitHub issues for similar problems
|
||||
5. Create a new issue with your specific Windows version and error details
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: September 2025
|
||||
**Tested On**: Windows 11, Windows 10, Ubuntu 22.04 LTS
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
#!/bin/bash
|
||||
# Windows Compatibility Verification Script
|
||||
# Run this script to check for Windows-incompatible files before committing
|
||||
|
||||
echo "🔍 Checking Windows compatibility..."
|
||||
echo "======================================"
|
||||
|
||||
# Check for files with problematic characters
|
||||
echo "Checking for files with Windows-problematic characters..."
|
||||
|
||||
# Files with colons
|
||||
colon_files=$(find . -name "*:*" -type f 2>/dev/null | grep -v "\.git" || true)
|
||||
if [ -n "$colon_files" ]; then
|
||||
echo "❌ Found files with colons (problematic for Windows):"
|
||||
echo "$colon_files"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ No files with colons found"
|
||||
fi
|
||||
|
||||
# Files with other problematic characters
|
||||
problematic_files=$(find . -name "*[<>|\"*?]*" -type f 2>/dev/null | grep -v "\.git" || true)
|
||||
if [ -n "$problematic_files" ]; then
|
||||
echo "❌ Found files with Windows-problematic characters:"
|
||||
echo "$problematic_files"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ No files with problematic characters found"
|
||||
fi
|
||||
|
||||
# Check for very long paths (Windows has 260 char limit)
|
||||
echo "Checking for overly long file paths..."
|
||||
long_paths=$(find . -type f 2>/dev/null | while read file; do
|
||||
if [ ${#file} -gt 240 ]; then
|
||||
echo "$file (${#file} chars)"
|
||||
fi
|
||||
done)
|
||||
|
||||
if [ -n "$long_paths" ]; then
|
||||
echo "⚠️ Found long file paths (may cause Windows issues):"
|
||||
echo "$long_paths"
|
||||
echo "Consider shortening these paths"
|
||||
else
|
||||
echo "✅ All file paths are reasonable length"
|
||||
fi
|
||||
|
||||
# Check .gitignore has Windows protection
|
||||
echo "Checking .gitignore for Windows protection..."
|
||||
if grep -q "Zone.Identifier" .gitignore; then
|
||||
echo "✅ .gitignore includes Windows file protection"
|
||||
else
|
||||
echo "❌ .gitignore missing Windows file protection"
|
||||
echo "Add these lines to .gitignore:"
|
||||
echo "*:Zone.Identifier"
|
||||
echo "*:*"
|
||||
echo "desktop.ini"
|
||||
echo "Thumbs.db"
|
||||
echo "*.lnk"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for case-sensitive naming conflicts
|
||||
echo "Checking for case-sensitive naming conflicts..."
|
||||
case_conflicts=$(find . -type f 2>/dev/null | sort -f | uniq -i -d)
|
||||
if [ -n "$case_conflicts" ]; then
|
||||
echo "❌ Found potential case-sensitive naming conflicts:"
|
||||
echo "$case_conflicts"
|
||||
echo "These files may conflict on case-insensitive Windows file systems"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ No case-sensitive naming conflicts found"
|
||||
fi
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "🎉 Windows Compatibility Check Complete!"
|
||||
echo "======================================"
|
||||
echo "✅ Repository is Windows-compatible"
|
||||
echo "✅ Ready for cross-platform development"
|
||||
echo ""
|
||||
echo "Next steps for Windows developers:"
|
||||
echo "1. See WINDOWS-DEVELOPMENT-GUIDE.md for setup instructions"
|
||||
echo "2. Use WSL2 or Docker Desktop for development"
|
||||
echo "3. Test on both Windows and Linux before committing"
|
||||
echo ""
|
||||
Loading…
Reference in New Issue