CrumbForest Naked Scanner - Server Deployment Guide

📋 Übersicht

Dieses Repository enthält die "naked" Version von CrumbForest - eine Docker-freie Installation für native LAMP-Server.

Status: ✅ Ready for Deployment
- Alle PHP-Dateien: ✅ Syntax OK
- Autoloader: ✅ PSR-4 konfiguriert
- Config-System: ✅ Funktional
- Directory-Struktur: ✅ Komplett

🔧 Server-Anforderungen

Mindestanforderungen

PHP: >= 8.1.0 (getestet mit 8.5.0)
MySQL: >= 8.0
Apache/Nginx: mit mod_rewrite (Apache) oder entsprechender Nginx-Config
Composer: für Dependency Management

PHP Extensions (erforderlich)

pdo
pdo_mysql
json
mbstring
curl

📦 Installation auf dem Server

1. Repository auf Server kopieren

# Auf dem Server (z.B. /var/www/crumbforest)
cd /var/www
git clone <dein-repo-url> crumbforest
# ODER via SCP/SFTP hochladen

cd crumbforest

2. Composer Dependencies installieren

composer install --no-dev --optimize-autoloader

3. .env Datei konfigurieren

WICHTIG: Folgende Werte MÜSSEN angepasst werden:

# 1. Basis-URL (deine Domain)
BASE_URL=https://crumbforest.deine-domain.de

# 2. MySQL Zugangsdaten
DB_HOST=localhost
DB_NAME=crumbforest
DB_USER=crumbforest_user
DB_PASS=SICHERES_PASSWORT_HIER

# 3. JWT Secret (CRITICAL!)
JWT_SECRET=$(openssl rand -base64 32)  # Generiere ein sicheres Secret!

# 4. Upload & Log Pfade (falls abweichend)
UPLOAD_DIR=/var/www/crumbforest/uploads
LOG_FILE=/var/www/crumbforest/logs/crumbforest.log

# 5. Netbox Integration (wenn verwendet)
NETBOX_URL=http://dein-netbox-server
NETBOX_TOKEN=dein_netbox_api_token

4. MySQL Datenbank einrichten

# MySQL als root
mysql -u root -p

# Datenbank und User anlegen
CREATE DATABASE crumbforest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'crumbforest_user'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';
GRANT ALL PRIVILEGES ON crumbforest.* TO 'crumbforest_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# Schema importieren
mysql -u crumbforest_user -p crumbforest < crumbforest_sql/schema.sql

5. Verzeichnis-Berechtigungen setzen

# Webserver-User (meist www-data oder apache)
sudo chown -R www-data:www-data /var/www/crumbforest

# Upload & Log Verzeichnisse beschreibbar machen
sudo chmod -R 755 /var/www/crumbforest
sudo chmod -R 775 /var/www/crumbforest/logs
sudo chmod -R 775 /var/www/crumbforest/uploads

# WICHTIG: .env vor Web-Zugriff schützen
sudo chmod 600 /var/www/crumbforest/.env

6. Webserver konfigurieren

Apache VirtualHost

<VirtualHost *:80>
    ServerName crumbforest.deine-domain.de
    DocumentRoot /var/www/crumbforest/web_root

    <Directory /var/www/crumbforest/web_root>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted

        # Rewrite Rules
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule ^ index.php [L]
    </Directory>

    # Zugriff auf .env verbieten
    <FilesMatch "^\.env">
        Require all denied
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/crumbforest_error.log
    CustomLog ${APACHE_LOG_DIR}/crumbforest_access.log combined
</VirtualHost>

# Apache Module aktivieren
sudo a2enmod rewrite
sudo systemctl restart apache2

Nginx Config (Alternative)

server {
    listen 80;
    server_name crumbforest.deine-domain.de;
    root /var/www/crumbforest/web_root;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    }

    location ~ /\.env {
        deny all;
    }

    location ~ /\.ht {
        deny all;
    }
}

✅ Validierung nach Installation

Führe auf dem Server aus:

cd /var/www/crumbforest
php check-setup.php

Erwartetes Ergebnis:

🎉 ALL CHECKS PASSED!
   Ready for server deployment.

ODER:

⚠️  X WARNING(S)
   Installation is functional but has warnings.

Manuelle Checks

Health-Check API:
bash curl http://localhost/api/health # Erwartete Antwort: {"status":"ok","service":"crumbforest-php"}
Frontend erreichbar:
bash curl http://localhost/ # Sollte HTML zurückgeben
Autoloader funktioniert:
bash php -r "require 'vendor/autoload.php'; echo 'OK';"

🔐 Sicherheits-Checklist (KRITISCH!)

[ ] .env ist nicht über Web erreichbar (chmod 600)
[ ] JWT_SECRET wurde auf einen sicheren Random-String geändert
[ ] MySQL User hat nur Zugriff auf crumbforest DB (nicht root!)
[ ] HTTPS/SSL ist aktiviert (Let's Encrypt empfohlen)
[ ] logs/ und uploads/ sind schreibbar, aber .htaccess geschützt
[ ] Firewall erlaubt nur Port 80/443 (und 22 für SSH)

🗂️ Projektstruktur

crumbforest_naked_scanner/
├── .env                          # Konfiguration (NICHT committen!)
├── composer.json                 # PHP Dependencies
├── check-setup.php               # Setup-Validator
├── doktor-setup.sh              # Setup-Script (optional)
│
├── web_root/                    # Document Root für Webserver
│   ├── index.php                # Main Router
│   ├── api/
│   │   └── index.php           # REST API
│   ├── public/                 # Frontend Assets (HTML, JS, CSS)
│   └── includes/               # PHP Classes (PSR-4)
│       ├── Config/
│       │   └── Config.php      # ✅ Config Manager (neu)
│       ├── Database/
│       │   └── Database.php    # PDO Wrapper
│       ├── Auth/
│       │   └── Auth.php        # JWT Authentication
│       ├── Services/
│       │   └── ScannerService.php
│       └── Integration/
│           └── NetboxClient.php
│
├── crumbforest_sql/
│   └── schema.sql              # MySQL Schema
│
└── logs/                       # Application Logs (writable!)

🚀 Nach der Installation

Ersten User anlegen

Temporär direkten DB-Zugriff nutzen:
```sql
-- Passwort-Hash generieren (z.B. mit password_hash in PHP)
-- Oder Login über API nutzen nach User-Insert

INSERT INTO users (username, password_hash, email, user_group, created_at)
VALUES (
'admin',
'$2y$10$...', -- password_hash('dein_passwort', PASSWORD_BCRYPT)
'admin@example.com',
1, -- Admin Group
NOW()
);
```

Via API (wenn ein Admin existiert):
bash curl -X POST http://your-server/api/auth/register \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \ -d '{ "username": "newuser", "password": "password123", "email": "user@example.com", "group": 10 }'

Frontend testen

Öffne im Browser: http://your-server/

API testen

# Login
curl -X POST http://your-server/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

# Sollte JWT Token zurückgeben

🐛 Troubleshooting

Problem: "Class not found"

# Autoloader neu generieren
composer dump-autoload -o

Problem: ".env file not found"

# Pfad prüfen
php -r "echo __DIR__;"
# .env muss im gleichen Verzeichnis wie composer.json sein

Problem: "Database connection failed"

# MySQL läuft?
sudo systemctl status mysql

# Credentials prüfen
mysql -u crumbforest_user -p crumbforest

Problem: "Permission denied" (Logs/Uploads)

sudo chown -R www-data:www-data /var/www/crumbforest
sudo chmod -R 775 /var/www/crumbforest/logs
sudo chmod -R 775 /var/www/crumbforest/uploads

📝 Wartung

Logs prüfen

tail -f /var/www/crumbforest/logs/crumbforest.log
tail -f /var/log/apache2/crumbforest_error.log

Backup

# Datenbank
mysqldump -u crumbforest_user -p crumbforest > backup_$(date +%Y%m%d).sql

# Uploads
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz /var/www/crumbforest/uploads/

🎯 Next Steps nach Deployment

SSL/TLS mit Let's Encrypt einrichten
Automated Backups konfigurieren
Monitoring aufsetzen (z.B. Uptime-Kuma)
Netbox Integration testen
Ollama/Qdrant Services installieren (wenn AI-Features genutzt werden)

Version: v0.0 #naked_admin
Stand: 2025-12-19
Autor: bmt