freeleaps-ops/apps/gitea-webhook-ambassador-python/README_ENHANCED.md

# Gitea Webhook Ambassador (Python Enhanced Version)

This is a Gitea Webhook Ambassador service rewritten in Python, providing the same features as the Go version, but with an added web interface and more management features.

## 🚀 Quick Start

### Method 1: Use the devbox script (recommended, same as Go version)

```bash
# Install dependencies
./devbox install

# Initialize database
./devbox init

# Start the service
./devbox start

# Check status
./devbox status

# View logs
./devbox logs

# Stop the service
./devbox stop
```

### Method 2: Use Makefile

```bash
# Install dependencies
make install

# Initialize database
make init

# Start the service (foreground)
make run

# Start the service (background)
make start

# Check status
make status

# View logs
make logs

# Stop the service
make stop
```

### Method 3: Use Python directly

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python -c "from app.models.database import create_tables; create_tables()"

# Start the service
python -m uvicorn app.main_enhanced:app --host 0.0.0.0 --port 8000
```

## 📁 Directory Structure (same as Go version)

```
gitea-webhook-ambassador-python/
├── app/                    # Application code
│   ├── auth/              # Authentication module
│   ├── handlers/          # API handlers
│   ├── models/            # Data models
│   ├── templates/         # HTML templates
│   ├── static/            # Static files
│   └── main_enhanced.py   # Main application entry
├── cmd/                   # CLI tools (same as Go version)
│   └── server/           # Server startup
├── configs/              # Configuration files (same as Go version)
│   └── config.yaml       # Main configuration file
├── data/                 # Data directory (same as Go version)
│   └── *.db             # SQLite database files
├── logs/                 # Log directory (same as Go version)
│   └── service.log      # Service log
├── devbox               # Startup script (same as Go version)
├── Makefile             # Build script (same as Go version)
├── requirements.txt     # Python dependencies
└── README_ENHANCED.md   # This document
```

## 🔧 Configuration

Edit the `configs/config.yaml` file:

```yaml
server:
  port: 8000
  webhookPath: "/webhook"
  secretHeader: "X-Gitea-Signature"
  secretKey: "admin-secret-key-change-in-production"

jenkins:
  url: "http://jenkins.example.com"
  username: "jenkins-user"
  token: "jenkins-api-token"
  timeout: 30

admin:
  token: "admin-api-token"

database:
  path: "data/gitea-webhook-ambassador.db"

logging:
  level: "info"
  format: "text"
  file: "logs/service.log"

worker:
  poolSize: 10
  queueSize: 100
  maxRetries: 3
  retryBackoff: 1

eventCleanup:
  interval: 3600
  expireAfter: 7200
```

## 🌐 Web Interface

After starting the service, visit the following addresses:

- **Login page**: http://localhost:8000
- **Dashboard**: http://localhost:8000/dashboard
- **API Docs**: http://localhost:8000/docs

### Default login credentials
- **Username**: admin
- **Password**: admin-secret-key-change-in-production

## 📊 Features

### ✅ Same features as Go version
- Gitea Webhook receiving and processing
- Jenkins job triggering
- Project mapping configuration
- Branch pattern matching
- Retry mechanism
- Logging

### 🆕 Python version enhancements
- **Web login interface**: Modern UI based on Bootstrap 5
- **Database storage**: SQLite database for API keys and configuration
- **JWT authentication**: 7-day valid JWT tokens
- **Frontend dashboard**: Multi-tab management interface
- **Auto redirect**: Unauthenticated users are redirected to login
- **Health check**: Service status monitoring
- **Statistics**: Request statistics and performance metrics

## 🔌 API Endpoints

### Authentication
- `POST /api/auth/login` - User login
- `GET /api/auth/verify` - Verify JWT token

### Project Management
- `GET /api/projects` - Get project list
- `POST /api/projects` - Create new project
- `PUT /api/projects/{id}` - Update project
- `DELETE /api/projects/{id}` - Delete project

### API Key Management
- `GET /api/keys` - Get API key list
- `POST /api/keys` - Create new API key
- `DELETE /api/keys/{id}` - Delete API key

### System Monitoring
- `GET /api/health` - Health check
- `GET /api/stats` - Statistics
- `GET /api/logs` - View logs

### Webhook Handling
- `POST /webhook` - Gitea Webhook endpoint

## 🛠️ Development

### Run tests
```bash
# Use devbox
./devbox test

# Use Makefile
make test

# Run directly
python test_enhanced_features.py
```

### Code linting
```bash
# Use Makefile
make lint

# Run directly
flake8 app/ --max-line-length=120 --ignore=E501,W503
```

### Clean up
```bash
# Use devbox
./devbox clean

# Use Makefile
make clean
```

## 🐳 Docker Deployment

### Build image
```bash
# Use Makefile
make docker-build

# Build directly
docker build -t gitea-webhook-ambassador:latest .
```

### Run container
```bash
docker run -d \
  --name gitea-webhook-ambassador \
  -p 8000:8000 \
  -v $(pwd)/configs:/app/configs \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  gitea-webhook-ambassador:latest
```

## 📈 Comparison with Go Version

| Feature | Go Version | Python Version |
|---------|------------|---------------|
| **Startup** | `./devbox start` | `./devbox start` |
| **Directory Structure** | Standard Go project | Same as Go version |
| **Config File** | `configs/config.yaml` | `configs/config.yaml` |
| **Log Directory** | `logs/` | `logs/` |
| **Data Directory** | `data/` | `data/` |
| **Web Interface** | ❌ No | ✅ Full dashboard |
| **Database** | ❌ No | ✅ SQLite |
| **JWT Auth** | ❌ No | ✅ 7-day validity |
| **API Key Management** | ❌ No | ✅ Database storage |
| **Health Check** | ✅ Basic | ✅ Enhanced |
| **Performance** | 🚀 Very high | 🚀 High |

## 🔄 Migration Guide

### Migrate from Go version to Python version

1. **Stop Go service**
   ```bash
   cd /path/to/go-version
   ./devbox stop
   ```

2. **Start Python service**
   ```bash
   cd /path/to/python-version
   ./devbox install
   ./devbox init
   ./devbox start
   ```

3. **Verify service**
   ```bash
   ./devbox status
   curl http://localhost:8000/api/health
   ```

4. **Configure Webhook**
   - Update Gitea Webhook URL to the new Python service address
   - Ensure Jenkins configuration is correct

## 🆘 Troubleshooting

### Common Issues

**1. Port 8000 is occupied**
```bash
# Check port usage
lsof -i :8000

# Stop the occupying process
sudo kill -9 <PID>
```

**2. Virtual environment issues**
```bash
# Recreate virtual environment
rm -rf venv
./devbox install
```

**3. Database issues**
```bash
# Reinitialize database
./devbox init
```

**4. Permission issues**
```bash
# Set script permissions
chmod +x devbox
```

### View logs
```bash
# View real-time logs
./devbox follow

# View latest logs
./devbox logs

# View full logs
tail -f logs/service.log
```

## 📞 Support

If you have any issues, please check:
1. Service status: `./devbox status`
2. Log information: `./devbox logs`
3. Configuration file: `configs/config.yaml`
4. Network connection: `curl http://localhost:8000/api/health`