SIDEL_ScriptsManager/README.md

# ScriptsManager

A comprehensive web-based application for managing and executing Python scripts with multi-user support, conda environment integration, and real-time monitoring.

## Features

- **Multi-user support** with role-based access control
- **Multi-language interface** (English, Spanish, Italian, French)
- **Conda environment integration** for isolated script execution
- **Real-time log streaming** with WebSocket connections
- **Script parameter management** with web forms
- **Dark/Light theme support**
- **Responsive web interface** with Bootstrap 5
- **Script discovery and automatic registration**
- **Web interface support** for scripts with UI components
- **Project-based data isolation** for multi-user environments

## Requirements

- Python 3.8+
- Conda (for environment management)
- Modern web browser with WebSocket support

## Installation

1. **Clone or extract the project:**
   ```bash
   cd SIDELManagerScripts
   ```

2. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Initialize the database:**
   ```bash
   python scripts/init_db.py
   ```

4. **Create admin user (if not created by init_db):**
   ```bash
   python scripts/create_admin.py
   ```

## Quick Start

1. **Start the application:**
   ```bash
   python scripts/run_app.py
   ```

2. **Open your browser and navigate to:**
   ```
   http://localhost:5000
   ```

3. **Login with default admin credentials:**
   - Username: `admin`
   - Password: `admin123`
   - **Important:** Change the password after first login!

4. **Explore the dashboard and script groups**

## Project Structure

```
SIDELManagerScripts/
├── app/                          # Main application package
│   ├── config/                   # Configuration files
│   │   ├── config.py            # App configuration
│   │   ├── database.py          # Database setup
│   │   └── permissions.py       # Role-based permissions
│   ├── models/                   # Database models
│   │   ├── user.py              # User and role models
│   │   └── script.py            # Script and group models
│   ├── services/                 # Business logic services
│   │   ├── conda_service.py     # Conda environment management
│   │   ├── discovery_service.py # Script discovery and parsing
│   │   ├── script_executor.py   # Script execution engine
│   │   ├── data_manager.py      # Multi-user data isolation
│   │   ├── port_manager.py      # Dynamic port allocation
│   │   └── translation_service.py # Multi-language support
│   ├── templates/                # HTML templates
│   │   ├── base.html            # Base template
│   │   ├── login.html           # Login page
│   │   ├── dashboard.html       # Main dashboard
│   │   └── script_group.html    # Script group view
│   ├── static/                   # Static assets
│   │   ├── css/                 # Stylesheets
│   │   ├── js/                  # JavaScript files
│   │   └── translations/        # Language files
│   └── __init__.py              # App factory
├── backend/                      # Script groups directory
│   └── script_groups/           # Individual script collections
├── scripts/                      # Utility scripts
│   ├── init_db.py              # Database initialization
│   ├── create_admin.py         # Admin user creation
│   └── run_app.py              # Application runner
├── instance/                     # Instance-specific files
├── logs/                        # Application logs
├── requirements.txt             # Python dependencies
├── requirements-dev.txt         # Development dependencies
└── README.md                   # This file
```

## Script Groups

Script groups are collections of related Python scripts stored in the `app/backend/script_groups/` directory. Each group contains:

- **metadata.json**: Group configuration and script list
- **Python scripts**: The actual executable scripts
- **Optional conda environment**: Isolated execution environment

### Creating Script Groups

1. Create a new directory in `app/backend/script_groups/`
2. Add a `metadata.json` file with group configuration
3. Add your Python scripts with proper parameter headers
4. Restart the application to discover new scripts

### Example metadata.json:
```json
{
  "name": "data_processing",
  "display_name": "Data Processing Tools",
  "description": "Scripts for data analysis and processing",
  "conda_env": "data_science",
  "scripts": [
    "data_analyzer.py",
    "csv_processor.py"
  ]
}
```

### Script Parameter Headers

Scripts can define parameters in their docstring headers:
```python
"""
Script Name
Script description

Parameters:
- input_file: Input file path
- output_format: Output format (json/csv/xlsx)

Interface: Yes/No
"""
```

## Configuration

### Environment Variables

- `FLASK_ENV`: Application environment (development/production)
- `SECRET_KEY`: Flask secret key for sessions
- `DATABASE_URL`: Database connection string
- `CONDA_PATH`: Path to conda executable

### Database Configuration

The application uses SQLite by default. For production, configure PostgreSQL or MySQL in `app/config/config.py`.

### Conda Integration

The application automatically detects conda environments and can execute scripts in isolated environments. Ensure conda is installed and accessible in your PATH.

## Multi-Language Support

The application supports multiple languages:
- English (en)
- Spanish (es)
- Italian (it)
- French (fr)

Language files are stored in `app/static/translations/` and can be extended with additional languages.

## Security Features

- **Role-based access control** (Admin, User, Viewer)
- **Session management** with secure cookies
- **CSRF protection** for forms
- **Input validation** for script parameters
- **Process isolation** for script execution
- **Multi-user data separation**

## API Endpoints

The application provides REST API endpoints for:
- Script execution: `POST /api/scripts/run`
- Log retrieval: `GET /api/scripts/{id}/logs`
- Interface access: `GET /api/scripts/{id}/interface`
- User management: `/api/users/*`
- System status: `GET /api/status`

## WebSocket Events

Real-time updates are provided via WebSocket:
- `script_started`: Script execution begins
- `script_completed`: Script execution finishes
- `script_failed`: Script execution fails
- `script_output`: Real-time log output
- `system_notification`: System messages

## Development

### Setting up Development Environment

1. Install development dependencies:
   ```bash
   pip install -r requirements-dev.txt
   ```

2. Set Flask environment:
   ```bash
   export FLASK_ENV=development
   ```

3. Enable debug mode:
   ```bash
   export FLASK_DEBUG=1
   ```

### Running Tests

```bash
python -m pytest tests/
```

### Code Style

The project follows PEP 8 style guidelines. Use flake8 for linting:
```bash
flake8 app/
```

## Deployment

### Production Deployment

1. Set production environment:
   ```bash
   export FLASK_ENV=production
   ```

2. Configure a production WSGI server (gunicorn):
   ```bash
   pip install gunicorn
   gunicorn -w 4 -b 0.0.0.0:5000 "app:create_app()"
   ```

3. Set up a reverse proxy (nginx/Apache)
4. Configure SSL certificates
5. Set up monitoring and logging

### Docker Deployment

A Dockerfile can be created for containerized deployment:
```dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "scripts/run_app.py"]
```

## Troubleshooting

### Common Issues

1. **Database errors**: Run `python scripts/init_db.py` to recreate database
2. **Conda not found**: Ensure conda is in your PATH
3. **Port conflicts**: Check that port 5000 is available
4. **Permission errors**: Ensure proper file permissions for script execution

### Log Files

Application logs are stored in the `logs/` directory:
- `app.log`: General application logs
- `scripts.log`: Script execution logs
- `errors.log`: Error logs

### Debug Mode

Enable debug mode for detailed error messages:
```bash
export FLASK_DEBUG=1
python scripts/run_app.py
```

## Support

For issues and questions:
1. Check the troubleshooting section
2. Review application logs
3. Verify configuration settings
4. Check script group metadata and permissions

## License

This project is licensed under the MIT License. See LICENSE file for details.