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)

# 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

# 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

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

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

# Use devbox
./devbox test

# Use Makefile
make test

# Run directly
python test_enhanced_features.py

Code linting

# Use Makefile
make lint

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

Clean up

# Use devbox
./devbox clean

# Use Makefile
make clean

🐳 Docker Deployment

Build image

# Use Makefile
make docker-build

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

Run container

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

   cd /path/to/go-version
   ./devbox stop
   

2. Start Python service

   cd /path/to/python-version
   ./devbox install
   ./devbox init
   ./devbox start
   

3. Verify service

   ./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

# Check port usage
lsof -i :8000

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

2. Virtual environment issues

# Recreate virtual environment
rm -rf venv
./devbox install

3. Database issues

# Reinitialize database
./devbox init

4. Permission issues

# Set script permissions
chmod +x devbox

View logs

# 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