refactor: clean repository structure for v0.1.0 open source release
- Remove Go artifacts (cmd/, internal/, pkg/, go.mod) - Move furt-lua/* content to repository root - Restructure as clean src/, config/, scripts/, tests/ layout - Rewrite README.md as practical tool documentation - Remove timeline references and marketing language - Clean .gitignore from Go-era artifacts - Update config/server.lua with example.org defaults - Add .env.production to .gitignore for security Repository now ready for open source distribution with minimal, focused structure and generic configuration templates. close issue DAW/furt#86
This commit is contained in:
parent
87c935379b
commit
be3b9614d0
38 changed files with 280 additions and 5892 deletions
187
docs/lua-implementation-reference.md
Normal file
187
docs/lua-implementation-reference.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Furt Lua HTTP-Server
|
||||
|
||||
**Pure Lua HTTP-Server für Dragons@Work API-Gateway**
|
||||
*Week 1 Implementation - Digital Sovereignty Project*
|
||||
|
||||
## Überblick
|
||||
|
||||
Furt ist der erste Schritt zur Migration des API-Gateways von Go auf C+Lua für maximale digitale Souveränität. Diese Implementierung startet mit reinem Lua und bildet die Grundlage für die spätere C+Lua-Hybridarchitektur.
|
||||
|
||||
## Funktionen
|
||||
|
||||
- ✅ **HTTP-Server** mit lua-socket
|
||||
- ✅ **JSON API** Endpoints
|
||||
- ✅ **Request/Response Parsing**
|
||||
- ✅ **Basic Routing**
|
||||
- ✅ **Mail-Service-Grundgerüst**
|
||||
- ✅ **Health-Check**
|
||||
- ✅ **Error Handling**
|
||||
- ✅ **Automated Tests**
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Erforderlich:**
|
||||
- `lua` 5.4+
|
||||
- `lua-socket` (HTTP-Server)
|
||||
- `lua-cjson` (JSON-Verarbeitung)
|
||||
|
||||
**Arch Linux:**
|
||||
```bash
|
||||
pacman -S lua lua-socket lua-cjson
|
||||
```
|
||||
|
||||
**Ubuntu:**
|
||||
```bash
|
||||
apt install lua5.4 lua-socket lua-cjson
|
||||
```
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
```
|
||||
furt-lua/
|
||||
├── src/
|
||||
│ └── main.lua # HTTP-Server (< 200 Zeilen)
|
||||
├── config/
|
||||
│ └── server.lua # Konfiguration
|
||||
├── scripts/
|
||||
│ ├── start.sh # Server starten
|
||||
│ └── test_curl.sh # Manuelle Tests
|
||||
├── tests/
|
||||
│ └── test_http.lua # Automatische Tests
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Installation & Start
|
||||
|
||||
**1. Repository Setup:**
|
||||
```bash
|
||||
mkdir furt-lua
|
||||
cd furt-lua
|
||||
|
||||
# Dateien erstellen (aus Claude-Artefakten)
|
||||
# main.lua, config/server.lua, scripts/start.sh, etc.
|
||||
```
|
||||
|
||||
**2. Executable machen:**
|
||||
```bash
|
||||
chmod +x scripts/start.sh
|
||||
chmod +x scripts/test_curl.sh
|
||||
```
|
||||
|
||||
**3. Server starten:**
|
||||
```bash
|
||||
./scripts/start.sh
|
||||
```
|
||||
|
||||
**Server läuft auf:** http://127.0.0.1:8080
|
||||
|
||||
## API-Endpoints
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
GET /health
|
||||
→ {"status":"healthy","service":"furt-lua","version":"1.0.0"}
|
||||
```
|
||||
|
||||
### Test Endpoint
|
||||
```bash
|
||||
POST /test
|
||||
Content-Type: application/json
|
||||
{"test": "data"}
|
||||
→ {"message":"Test endpoint working"}
|
||||
```
|
||||
|
||||
### Mail Service
|
||||
```bash
|
||||
POST /v1/mail/send
|
||||
Content-Type: application/json
|
||||
{
|
||||
"name": "Test User",
|
||||
"email": "test@example.com",
|
||||
"message": "Test message"
|
||||
}
|
||||
→ {"success":true,"message":"Mail queued for sending"}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
**Automatische Tests:**
|
||||
```bash
|
||||
# Server muss laufen!
|
||||
lua tests/test_http.lua
|
||||
```
|
||||
|
||||
**Manuelle curl-Tests:**
|
||||
```bash
|
||||
./scripts/test_curl.sh
|
||||
```
|
||||
|
||||
**Quick Test:**
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8080/test \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"test":"data"}'
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
**Mail-SMTP (Environment Variables):**
|
||||
```bash
|
||||
export FURT_MAIL_USERNAME="your_email@dragons-at-work.de"
|
||||
export FURT_MAIL_PASSWORD="your_password"
|
||||
```
|
||||
|
||||
**Server-Config:** `config/server.lua`
|
||||
- Port, Host ändern
|
||||
- API-Keys definieren
|
||||
- SMTP-Einstellungen
|
||||
|
||||
## Week 1 Status
|
||||
|
||||
✅ **Tag 1:** HTTP-Server basic functionality
|
||||
✅ **Tag 2:** Request/Response parsing
|
||||
✅ **Tag 3:** JSON handling, Mail endpoint structure
|
||||
✅ **Tag 4:** Routing, Error handling
|
||||
✅ **Tag 5:** Testing, Documentation
|
||||
|
||||
**Success Criteria erreicht:**
|
||||
- ✅ `curl -X POST http://localhost:8080/test` → HTTP 200 ✓
|
||||
- ✅ Alle Module < 200 Zeilen ✓
|
||||
- ✅ JSON Request/Response ✓
|
||||
- ✅ /v1/mail/send Endpoint ✓
|
||||
|
||||
## Nächste Schritte (Week 2)
|
||||
|
||||
1. **SMTP-Integration** - Echte Mail-Versendung
|
||||
2. **API-Key-Authentication** - Security-Layer
|
||||
3. **Hugo-Integration** - POST-based Form-Handling
|
||||
4. **HTTPS** mit lua-ssl
|
||||
|
||||
## Technologie-Philosophie
|
||||
|
||||
- **Lua:** PUC-Rio University (echte Unabhängigkeit)
|
||||
- **Minimale Dependencies:** < 5 externe Libraries
|
||||
- **Modulare Architektur:** < 200 Zeilen pro Datei
|
||||
- **Transparenter Code:** Jede Zeile verstehbar
|
||||
- **Corporate-frei:** Keine Google/Microsoft/etc. Dependencies
|
||||
|
||||
**Teil der Dragons@Work Tech-Souveränitätsstrategie**
|
||||
|
||||
## Development
|
||||
|
||||
**Code-Stil:**
|
||||
- Module < 200 Zeilen
|
||||
- Funktionen < 50 Zeilen
|
||||
- Klare, lesbare Namen
|
||||
- Error-Handling für alles
|
||||
|
||||
**Testing-Pattern:**
|
||||
- Jede Funktion testbar
|
||||
- HTTP-Integration-Tests
|
||||
- curl-basierte Verifikation
|
||||
|
||||
---
|
||||
|
||||
**Week 1 Challenge: COMPLETE ✅**
|
||||
*Foundation für souveräne API-Gateway-Architektur gelegt.*
|
||||
|
||||
139
docs/production_checklist.md
Normal file
139
docs/production_checklist.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
# Furt API-Gateway Production Deployment Checklist
|
||||
|
||||
## 🔐 Security Configuration
|
||||
|
||||
### API Keys
|
||||
- [ ] Generate secure API keys (32+ characters)
|
||||
- [ ] Set HUGO_API_KEY in .env.production
|
||||
- [ ] Set ADMIN_API_KEY in .env.production
|
||||
- [ ] Remove/change all development keys
|
||||
- [ ] Verify API key permissions in config/server.lua
|
||||
|
||||
### CORS Configuration
|
||||
- [ ] Set production domains in CORS_ALLOWED_ORIGINS
|
||||
- [ ] Remove localhost/development origins
|
||||
- [ ] Test CORS with production domains
|
||||
|
||||
### Endpoints
|
||||
- [ ] Disable test endpoint (ENABLE_TEST_ENDPOINT=false)
|
||||
- [ ] Remove any debug endpoints
|
||||
- [ ] Verify only required endpoints are exposed
|
||||
|
||||
## 📧 SMTP Configuration
|
||||
|
||||
- [ ] Configure production SMTP server
|
||||
- [ ] Test SMTP authentication
|
||||
- [ ] Set proper FROM and TO addresses
|
||||
- [ ] Verify mail delivery works
|
||||
- [ ] Test mail sending with rate limits
|
||||
|
||||
## 🔧 Server Configuration
|
||||
|
||||
### Environment
|
||||
- [ ] Copy .env.production to .env
|
||||
- [ ] Set GATEWAY_HOST (127.0.0.1 for internal)
|
||||
- [ ] Set GATEWAY_PORT (8080 default)
|
||||
- [ ] Set LOG_LEVEL to "warn" or "error"
|
||||
|
||||
### Performance
|
||||
- [ ] Verify rate limits are appropriate
|
||||
- [ ] Test concurrent load handling
|
||||
- [ ] Monitor memory usage under load
|
||||
- [ ] Test restart behavior
|
||||
|
||||
## 🛡️ Security Testing
|
||||
|
||||
### Authentication
|
||||
- [ ] Test invalid API keys return 401
|
||||
- [ ] Test missing API keys return 401
|
||||
- [ ] Test permission system works correctly
|
||||
- [ ] Test IP restrictions (if configured)
|
||||
|
||||
### Rate Limiting
|
||||
- [ ] Test rate limits trigger at correct thresholds
|
||||
- [ ] Test 429 responses are returned
|
||||
- [ ] Test rate limit headers are present
|
||||
- [ ] Test rate limit cleanup works
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### File Permissions
|
||||
- [ ] Lua files readable by server user
|
||||
- [ ] .env file protected (600 permissions)
|
||||
- [ ] Log directory writable
|
||||
- [ ] No world-readable sensitive files
|
||||
|
||||
### Process Management
|
||||
- [ ] Configure systemd service (if applicable)
|
||||
- [ ] Test automatic restart on failure
|
||||
- [ ] Configure log rotation
|
||||
- [ ] Set up monitoring/health checks
|
||||
|
||||
### Reverse Proxy (if applicable)
|
||||
- [ ] Configure nginx/apache reverse proxy
|
||||
- [ ] Set up SSL termination
|
||||
- [ ] Configure rate limiting at proxy level
|
||||
- [ ] Test proxy → furt communication
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Health Checks
|
||||
- [ ] /health endpoint responds correctly
|
||||
- [ ] Set up external monitoring (e.g., Uptime Kuma)
|
||||
- [ ] Configure alerting for service down
|
||||
- [ ] Test health check under load
|
||||
|
||||
### Logging
|
||||
- [ ] Configure appropriate log level
|
||||
- [ ] Set up log rotation
|
||||
- [ ] Monitor log file sizes
|
||||
- [ ] Review error patterns
|
||||
|
||||
### Metrics
|
||||
- [ ] Monitor request rates
|
||||
- [ ] Monitor response times
|
||||
- [ ] Monitor memory usage
|
||||
- [ ] Monitor SMTP connection health
|
||||
|
||||
## 🧪 Integration Testing
|
||||
|
||||
### Hugo Integration
|
||||
- [ ] Test contact forms submit successfully
|
||||
- [ ] Test error handling displays correctly
|
||||
- [ ] Test rate limiting shows user-friendly messages
|
||||
- [ ] Test CORS works with production domains
|
||||
|
||||
### Mail Delivery
|
||||
- [ ] Send test emails through all forms
|
||||
- [ ] Verify emails arrive correctly formatted
|
||||
- [ ] Test email content encoding
|
||||
- [ ] Test attachment handling (if applicable)
|
||||
|
||||
## 📝 Documentation
|
||||
|
||||
- [ ] Document API endpoints for other developers
|
||||
- [ ] Document configuration options
|
||||
- [ ] Document troubleshooting procedures
|
||||
- [ ] Document backup/restore procedures
|
||||
|
||||
## 🔄 Backup & Recovery
|
||||
|
||||
- [ ] Document configuration files to backup
|
||||
- [ ] Test service restart procedures
|
||||
- [ ] Document rollback procedures
|
||||
- [ ] Test recovery from configuration errors
|
||||
|
||||
## ✅ Final Verification
|
||||
|
||||
- [ ] All API endpoints respond correctly
|
||||
- [ ] All security measures tested
|
||||
- [ ] Performance meets requirements
|
||||
- [ ] Monitoring and alerting configured
|
||||
- [ ] Documentation complete
|
||||
- [ ] Team trained on operations
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** $(date +%Y-%m-%d)
|
||||
**Deployed By:** _______________
|
||||
**Deployment Date:** _______________
|
||||
Loading…
Add table
Add a link
Reference in a new issue