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:

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:

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)

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:

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

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

# Windows compatibility - files with problematic characters
*:Zone.Identifier
*:*
desktop.ini
Thumbs.db
*.lnk

Cross-Platform Workflow

Development Cycle

1. Windows Development:

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

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

   # 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

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

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:

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

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

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

   # Configure Git to handle line endings
   git config --global core.autocrlf true
   

2. Path Length Limitations:

   # Enable long paths on Windows 10+
   git config --global core.longpaths true
   

3. File Permission Issues:

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

# 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

# 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

# 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