SIDEL_ScriptsManager/WINDOWS-DEVELOPMENT-GUIDE.md

# 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

### Step 1: Configure Git for Gitea

#### Option A: Using Personal Access Token (Most Secure)
1. Go to your Gitea instance: `https://gitea.casaparma.dscloud.me`
2. Navigate to Settings → Applications → Generate New Token
3. Copy the generated token
4. Configure Git credentials:

```bash
git config --global credential.helper store
git config --global user.name "Your-Gitea-Username"
git config --global user.email "your-email@domain.com"
```

5. Clone the repository:
```bash
git clone https://gitea.casaparma.dscloud.me/Miguel/SIDEL_ScriptsManager.git
```

6. When prompted, use your username and the **token** as password.

#### Option B: Using Username in URL (Quick Setup)
```bash
git clone https://YOUR-USERNAME@gitea.casaparma.dscloud.me/Miguel/SIDEL_ScriptsManager.git
cd SIDEL_ScriptsManager
```

This will prompt for password only once and store it securely.

### Step 2: Development Environment 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 data persists in `data/postgres/`.

## Git Configuration Troubleshooting

### Credential Issues

If you're repeatedly asked for credentials:

```bash
# Check current configuration
git config --list | grep credential

# Reset credential helper
git config --global --unset credential.helper
git config --global credential.helper store

# For Gitea specifically, use username in URL
git remote set-url origin https://USERNAME@gitea.casaparma.dscloud.me/Miguel/SIDEL_ScriptsManager.git
```

### Token Authentication

When using Personal Access Tokens:
- Username: Your Gitea username
- Password: The generated token (NOT your regular password)

### Windows-Specific Git Issues

```bash
# If you get line ending warnings
git config --global core.autocrlf true

# If you get filename issues
git config --global core.protectNTFS false
```

### Verify Your Configuration

```bash
# Test your setup
git fetch origin
git status

# Check remotes
git remote -v

# Check user configuration
git config user.name
git config user.email
```

### 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