3.6 KiB
Formeleon 🦎
Mandantenfähiger, hochflexibler Formular-Generator mit nahtloser Website-Integration und integriertem Bot-Schutz.
Read this in English: README.EN.md
📋 Überblick
Formeleon ist ein zentral gehosteter Service (ChamäleonCloud), der es Webseitenbetreibern (Mandanten) ermöglicht, dynamische Formulare ohne Backend-Aufwand per HTML/JavaScript-Snippet in bestehende Webseiten einzubetten.
Kern-Features
- Nahtlose Integration: Einbettung via JS-Snippet ("Chamäleon-Effekt").
- Maximale Feldvariabilität: Dynamische JSON-Payloads via SQLite/SQLAlchemy.
- Integrierte Sicherheit: OIDC-Integration (Zitadel), Public-Key Handshake, Origin/Referer-Validierung & reCAPTCHA v3 Support.
- UX & Bot-Protection: Integriertes Ampel-System (Laderad/Clearance) für Absende-Buttons.
- Reporting & Export: Daten-Exports (CSV/JSON/YAML) per Stream oder automatisierte E-Mail-Dumps.
🛠️ Tech-Stack
- Backend: Python 3.13, Flask (Blueprint-Architektur), Flask-SQLAlchemy, Flask-Migrate (Alembic)
- Frontend (Admin-Panel): Bootstrap 5, Mithril.js / HTML5
- Authentication: OIDC via Zitadel (Admin-Panel)
- Deployment: Docker, Gunicorn, Gitea Actions (Runner)
🚀 Schnellstart (Lokal / Docker-less)
Das Projekt kann auf Windows/Linux komplett ohne Docker in einer Virtual Environment entwickelt werden:
-
Repository klonen & Umgebung einrichten:
python -m venv venv # Auf Linux/Mac: source venv/bin/activate # Auf Windows: venv\Scripts\activate pip install -r requirements.txt -
Umgebungsvariablen (optional): (Formeleon startet standardmäßig im Dev-Mode mit einer lokalen SQLite-DB
formeleon.db) -
Datenbank initialisieren & starten:
# Migration-Repository initialisieren (nur einmalig!) flask db init # Datenbank-Schema erstellen flask db upgrade # Optionales Seeding mit Testdaten flask seed-db # Anwendung starten (auf Port 5000 mit Hot-Reload) flask run --port=5000 --debug
🐳 Schnellstart (Docker)
Für das vollständige Linux- / Staging-Gefühl kannst du Docker nutzen. Durch Volume-Mounts bleibt der Code synchron, und du kannst im Editor (Windows/Mac) programmieren.
# 1. Image bauen und Container starten
docker compose up --build
# 2. Anwendung beenden
# (Strg+C oder:)
docker compose down
# 3. Datenbank und Volumes komplett zurücksetzen
docker compose down -v && docker-compose up --build
Docker CLI-Kommandos ausführen
Du kannst flask Kommandos direkt gegen den laufenden Container feuern:
# Datenbank Migrationen anlegen
docker compose run --rm app flask db migrate -m "neue migration"
# Datenbank-Schema updaten
docker compose run --rm app flask db upgrade
# Datenbank mit Testdaten füllen
docker compose run --rm app flask seed-db
# Shell im Container öffnen
docker compose run --rm app bash
Zugriff auf die Anwendung
- Admin Dashboard: http://localhost:5000/admin/
- API Endpunkt: http://localhost:5000/api/v1/
- Health Check: http://localhost:5000/
📚 Dokumentation
AGENTS.md– Regelwerk und Anweisungen für KI-Coding-Agenten.ARCHITEKTUR.md– Detaillierte Systemarchitektur und Datenmodelle.docs/coding-standards.md– Header- und PyDoc-Dokumentationsstandards.docs/deployment.md– CI/CD-Pipeline und Docker-Deployment-Guide.docs/dev-guide.md– Entwickler-Handbuch, Mocking & Seeding.