Legal Document Crawler Service

Ein containerisierter Spring Boot Service zum Crawlen von Rechtsprechung, Gesetzen und Verwaltungsvorschriften von https://www.rechtsprechung-im-internet.de

🚀 Features

• 🐳 Docker-basiertes Setup mit vollständiger Container-Orchestrierung
• 🔍 Apache Solr Integration für performante Volltextsuche
• 📁 Duale Speicherung - XML-Dateien + Solr-Index für beste Flexibilität
• ⚡ Intelligente Sitemap-Discovery mit Gzip-Unterstützung
• 🚦 Rate Limiting und ethisches Crawling
• 📅 Scheduling für automatisierte Crawling-Sessions
• 🌐 REST API für Steuerung und Monitoring
• 📊 Nginx Reverse Proxy mit Load Balancing
• 🔧 Comprehensive Health Checks und Monitoring

🏛️ Unterstützte Gerichte

• BAG - Bundesarbeitsgericht
• BGH - Bundesgerichtshof
• BSG - Bundessozialgericht
• BVerwG - Bundesverwaltungsgericht

📋 Voraussetzungen

• Docker & Docker Compose (empfohlen)
• Alternativ: Java 17+ und Maven 3.8+

🚀 Quick Start mit Docker

# Repository klonen
git clone <repository-url>
cd law-crawler-service

# Komplettes System starten (Solr + Crawler + Nginx)
docker-compose up -d

# Logs verfolgen
docker-compose logs -f

# System stoppen
docker-compose down

🎯 Nach dem Start verfügbar:

• API: http://localhost:8080
• Nginx Gateway: http://localhost:8888
• Solr Admin: http://localhost:8983/solr
• Grafana Dashboards: http://localhost:3000 (admin/admin123)
• Prometheus Metrics: http://localhost:9090

🏗️ Architektur

                    ┌─────────────────┐    ┌─────────────────┐
                    │   Prometheus    │    │     Grafana     │
                    │   Metrics       │◄──►│   Dashboards    │
                    │   Port 9090     │    │   Port 3000     │
                    └─────────────────┘    └─────────────────┘
                              ▲                      ▲
                              │                      │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Nginx       │    │  Spring Boot    │    │   Apache Solr   │
│  Reverse Proxy  │◄──►│   Crawler App   │◄──►│   Search Index  │
│   Port 8888     │    │    Port 8080    │    │   Port 8983     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  XML File Store │    │  Loki + Promtail│
                       │ /app/data/legal │    │   Log Pipeline  │
                       └─────────────────┘    └─────────────────┘

🔍 Monitoring Stack

• Prometheus: Metrics collection (JVM, HTTP, Tomcat, Business metrics)
• Grafana: 3 Dashboards - System, Business, Logs
• Loki + Promtail: Log aggregation and real-time analysis
• Health Checks: Application and container-level monitoring

🔧 Konfiguration

Docker Profile (Standard)

# application-docker.yml
crawler:
  storage:
    type: solr
    base-path: /app/data/legal-documents
  solr:
    url: http://solr:8983/solr
    collection: legal-documents

Umgebungsvariablen

SPRING_PROFILES_ACTIVE=docker,solr
SOLR_URL=http://solr:8983/solr
SOLR_COLLECTION=legal-documents
JAVA_OPTS=-Xms512m -Xmx2g -XX:+UseG1GC

🌐 REST API

🕷️ Crawling starten

# Einzeldatum crawlen
POST http://localhost:8080/api/crawler/crawl?date=2025-01-15

# Mit Force-Update
POST http://localhost:8080/api/crawler/crawl?date=2025-01-15&forceUpdate=true

📊 Status abfragen

GET http://localhost:8080/api/crawler/status
# Response: {"totalDocuments":1247,"downloadedDocuments":1247,"pendingDocuments":0,...}

🔍 Dokumente suchen

GET http://localhost:8080/api/crawler/search?query=arbeitsrecht

🏛️ Dokumente nach Gericht

GET http://localhost:8080/api/crawler/documents/BAG?page=0&size=20

🧪 Sitemap-Optimierungen testen

GET http://localhost:8080/api/crawler/test/sitemap-optimizations
# Response: {"summary":"Tested 10 dates: 10 exist, 0 gzipped, 10 with content",...}

🔄 Fehlgeschlagene Downloads wiederholen

POST http://localhost:8080/api/crawler/retry-failed

📁 Speicherstruktur

Container-Volumes

# XML-Dateien (persistent)
crawler_data:/app/data/legal-documents/

# Log-Dateien (persistent)  
crawler_logs:/app/logs/

# Solr-Daten (persistent)
solr_data:/var/solr/data/

Dateiorganisation

/app/data/legal-documents/
├── bag/          # Bundesarbeitsgericht
│   ├── 2025/
│   │   ├── 01/   # Januar
│   │   └── 02/   # Februar  
├── bgh/          # Bundesgerichtshof
├── bsg/          # Bundessozialgericht
└── bverwg/       # Bundesverwaltungsgericht

📊 Monitoring & Dashboards

🚀 Monitoring-Stack starten

# Alle Services inklusive Monitoring starten
docker-compose --profile monitoring up -d

# Nur Monitoring-Services
docker-compose --profile monitoring up -d prometheus grafana loki promtail

📈 Grafana Dashboards

Nach dem Start verfügbar unter http://localhost:3000 (admin/admin123):

1. Legal Crawler System Dashboard

   • JVM Memory, CPU, Threads
   • HTTP Request Metrics (Response Times, Status Codes)
   • Tomcat Connection Pool Stats

2. Legal Crawler Business Dashboard

   • Document Download Counts
   • Crawling Activity Timeline
   • Search Request Statistics
   • Court-specific Metrics

3. Legal Crawler Logs Dashboard

   • Real-time Log Streaming
   • Error Log Analysis
   • Log Level Distribution
   • Crawler Activity Logs

🔍 Log-Analyse

# Logs in Grafana → Explore → Loki
{job="legal-crawler"}                           # Alle Crawler-Logs
{job="legal-crawler", level="ERROR"}           # Nur Fehler
{job="legal-crawler"} |~ "crawler|download"    # Crawler-Aktivitäten

📉 Load Testing & Daten-Generierung

# Einmalige Testdaten für Dashboards
./generate_test_data.sh

# Kontinuierliche Last (Hintergrund)
./simple_load_test.sh &

🔄 Container-Management

Status prüfen

docker-compose ps
docker-compose logs crawler-app
docker-compose logs solr
docker-compose --profile monitoring logs grafana

Einzelne Services neustarten

docker-compose restart crawler-app
docker-compose restart solr
docker-compose restart nginx

Solr-Daten zurücksetzen

# Alle Dokumente aus Solr löschen
curl -X POST "http://localhost:8983/solr/legal-documents/update?commit=true" \
     -H "Content-Type: text/xml" \
     --data-binary "<delete><query>*:*</query></delete>"

Kompletter Reset

# Alle Container und Volumes löschen
docker-compose down -v

# Neu starten  
docker-compose up -d

⏰ Automatisierung

Aktive Cron-Jobs

• Täglich 6:00 Uhr: Crawling der letzten 7 Tage
• Sonntags 2:00 Uhr: Vollständiger Crawl der letzten 30 Tage
• Alle 6 Stunden: Wiederholung fehlgeschlagener Downloads
• Stündlich: System Health Check

📊 Monitoring & Health Checks

Container Health Checks

# Crawler App Health
curl http://localhost:8080/actuator/health

# Solr Health
curl http://localhost:8983/solr/legal-documents/admin/ping

# Nginx Status
curl http://localhost:8888

Actuator Endpoints

• Health: http://localhost:8080/actuator/health
• Metrics: http://localhost:8080/actuator/metrics
• Info: http://localhost:8080/actuator/info
• Solr Stats: http://localhost:8080/actuator/solr

Solr Admin UI

• URL: http://localhost:8983/solr
• Collection: legal-documents
• Query Console: http://localhost:8983/solr/#/legal-documents/query

🧪 Entwicklung & Tests

Lokale Entwicklung

# Nur Solr starten für lokale Entwicklung
docker-compose up -d solr

# App lokal starten
SPRING_PROFILES_ACTIVE=solr mvn spring-boot:run

Tests ausführen

# Unit Tests
mvn test

# Mit Integration Tests
mvn verify

# Coverage Report
mvn jacoco:report

Build ohne Docker

mvn clean package
java -jar target/law-crawler-service-1.0.0-SNAPSHOT.jar

🔧 Technologie-Stack

🏗️ Backend

• Spring Boot 3.2.2 - Application Framework
• Java 17 - Runtime Environment
• Apache Solr 9.4.1 - Search Engine
• Spring Data - Data Access Layer
• Quartz Scheduler - Cron Jobs

🐳 Infrastructure

• Docker & Docker Compose - Containerization
• Nginx - Reverse Proxy & Load Balancer
• Eclipse Temurin 17 - JVM Runtime

📦 Libraries

• SolrJ - Solr Java Client
• Jetty HTTP Client - HTTP Communications
• JSoup - HTML/XML Parsing
• Apache HttpComponents - HTTP Client

🚨 Troubleshooting

🔍 Häufige Probleme

1. Container starten nicht

# Logs prüfen
docker-compose logs

# Ports prüfen
netstat -tulpn | grep -E ':(8080|8983|8888)'

# Volumes zurücksetzen
docker-compose down -v && docker-compose up -d

2. Solr Connection Failed

# Solr Health prüfen
curl http://localhost:8983/solr/admin/ping

# Container Networking prüfen
docker-compose exec crawler-app ping solr

3. ClassCastException in Logs

# Fixed in current version - update to latest image
docker-compose build crawler-app
docker-compose up -d

4. Jetty Client Errors

# Dependencies werden automatisch installiert
# Bei Problemen: Image neu bauen
docker-compose build --no-cache crawler-app

📋 Debug-Befehle

# Container Shell
docker-compose exec crawler-app bash
docker-compose exec solr bash

# Live-Logs
docker-compose logs -f crawler-app

# Resource-Verbrauch
docker stats

⚖️ Rechtliche Hinweise

• ✅ Respektiert robots.txt der Zielwebseite
• 🚦 Rate Limiting implementiert (2 Sekunden zwischen Requests)
• 🌐 Nur öffentlich verfügbare Dokumente
• ⚠️ Keine rechtliche Beratung durch diesen Service

🤝 Beitragen

1. Fork des Repositories erstellen
2. Feature Branch erstellen (git checkout -b feature/amazing-feature)
3. Tests hinzufügen und prüfen (mvn test)
4. Docker Build testen (docker-compose build)
5. Pull Request erstellen

📄 Lizenz

Dieses Projekt steht unter der MIT Lizenz.

---

🚀 Powered by Docker, Spring Boot & Apache Solr