🐧 CrumbForest Debian/Ubuntu Setup (Native LAMP)

Komplettes LAMP-Setup für Debian 11/12 und Ubuntu 20.04/22.04 LTS Server.

📋 Übersicht

Status: ✅ Production-Ready
- Debian 11 (Bullseye) / Debian 12 (Bookworm)
- Ubuntu 20.04 LTS / 22.04 LTS
- Native LAMP Stack (Apache, MariaDB, PHP)

🔧 Server-Anforderungen

Mindestanforderungen

OS: Debian 11+ oder Ubuntu 20.04+
RAM: 512 MB (1 GB empfohlen)
Disk: 2 GB frei
CPU: 1 Core (2+ empfohlen)
Network: Internet-Zugang für apt

Software

Apache: 2.4+
MariaDB: 10.5+
PHP: 8.1+ (8.2/8.3 empfohlen)
Composer: 2.x

📦 Installation

1. System Update

sudo apt update
sudo apt upgrade -y

2. Apache2 installieren

# Apache installieren
sudo apt install apache2 -y

# Module aktivieren
sudo a2enmod rewrite
sudo a2enmod ssl
sudo a2enmod headers

# Service starten
sudo systemctl start apache2
sudo systemctl enable apache2

# Status prüfen
sudo systemctl status apache2

Test: curl http://localhost sollte Apache Default-Page zeigen

3. MariaDB installieren

# MariaDB installieren
sudo apt install mariadb-server mariadb-client -y

# Service starten
sudo systemctl start mariadb
sudo systemctl enable mariadb

# Sicherheits-Setup
sudo mysql_secure_installation

mysql_secure_installation Antworten:

Enter current password: [ENTER]
Set root password? [Y/n] Y
Remove anonymous users? [Y/n] Y
Disallow root login remotely? [Y/n] Y
Remove test database? [Y/n] Y
Reload privilege tables? [Y/n] Y

4. PHP 8.2+ installieren

Option A: Debian/Ubuntu Default (PHP 8.1)

sudo apt install php libapache2-mod-php php-mysql php-cli php-curl php-json php-mbstring php-xml php-zip php-bcmath -y

Option B: Neuere PHP Version (empfohlen für 8.2+)

# Sury PPA für neuere PHP Versionen
sudo apt install software-properties-common ca-certificates lsb-release apt-transport-https -y

# PPA hinzufügen
sudo sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/sury-php.list'
wget -qO - https://packages.sury.org/php/apt.gpg | sudo apt-key add -

# Update & Install PHP 8.3
sudo apt update
sudo apt install php8.3 libapache2-mod-php8.3 php8.3-mysql php8.3-cli php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip php8.3-bcmath -y

PHP Version prüfen:

php -v
# Sollte: PHP 8.x.x (cli) zeigen

5. Composer installieren

# Composer herunterladen
curl -sS https://getcomposer.org/installer | php

# Global verfügbar machen
sudo mv composer.phar /usr/local/bin/composer

# Verifizieren
composer --version

6. Xdebug installieren (Optional - für Coverage)

# Xdebug via PECL
sudo apt install php-pear php-dev -y
sudo pecl install xdebug

# Xdebug aktivieren
echo "zend_extension=xdebug.so" | sudo tee -a /etc/php/8.3/cli/php.ini
echo "xdebug.mode=coverage,develop" | sudo tee -a /etc/php/8.3/cli/php.ini

# Apache PHP auch
echo "zend_extension=xdebug.so" | sudo tee -a /etc/php/8.3/apache2/php.ini
echo "xdebug.mode=coverage,develop" | sudo tee -a /etc/php/8.3/apache2/php.ini

🗄️ Datenbank Setup

Datenbank & User erstellen

# Als root einloggen
sudo mysql

# In MySQL Shell:
CREATE DATABASE crumbforest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE crumbforest_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'crumbforest_user'@'localhost' IDENTIFIED BY 'SICHERES_PASSWORT_HIER';

GRANT ALL PRIVILEGES ON crumbforest.* TO 'crumbforest_user'@'localhost';
GRANT ALL PRIVILEGES ON crumbforest_test.* TO 'crumbforest_user'@'localhost';

FLUSH PRIVILEGES;
EXIT;

Schema importieren

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

# Verifizieren
mysql -u crumbforest_user -p crumbforest -e "SHOW TABLES;"

📁 Projekt Setup

1. Projekt-Verzeichnis anlegen

# Als root oder mit sudo
sudo mkdir -p /var/www/crumbforest
cd /var/www/crumbforest

# Projekt clonen oder hochladen
sudo git clone YOUR_REPO_URL .
# ODER via SCP/SFTP hochladen

2. Dependencies installieren

cd /var/www/crumbforest
sudo composer install --no-dev --optimize-autoloader

3. .env konfigurieren

sudo cp .env .env.backup  # falls schon vorhanden
sudo nano .env

Wichtige Anpassungen:

# Base URL
BASE_URL=http://your-server-ip-or-domain

# Database
DB_HOST=localhost
DB_NAME=crumbforest
DB_USER=crumbforest_user
DB_PASS=DEIN_SICHERES_PASSWORT

# JWT Secret (KRITISCH!)
JWT_SECRET=$(openssl rand -base64 32)

# Paths
UPLOAD_DIR=/var/www/crumbforest/web_root/uploads
LOG_FILE=/var/www/crumbforest/logs/crumbforest.log

4. Permissions setzen

# Owner auf Apache-User setzen
sudo chown -R www-data:www-data /var/www/crumbforest

# Base permissions
sudo chmod -R 755 /var/www/crumbforest

# Writable directories
sudo chmod -R 775 /var/www/crumbforest/logs
sudo chmod -R 775 /var/www/crumbforest/web_root/uploads

# .env schützen
sudo chmod 600 /var/www/crumbforest/.env

# Logs erstellen
sudo mkdir -p /var/www/crumbforest/logs
sudo touch /var/www/crumbforest/logs/crumbforest.log
sudo chown www-data:www-data /var/www/crumbforest/logs/crumbforest.log

🌐 Apache VirtualHost

1. VirtualHost Config erstellen

sudo nano /etc/apache2/sites-available/crumbforest.conf

Inhalt:

<VirtualHost *:80>
    ServerName your-domain.com
    ServerAlias www.your-domain.com

    DocumentRoot /var/www/crumbforest/web_root

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

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

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

    # Logs
    ErrorLog ${APACHE_LOG_DIR}/crumbforest_error.log
    CustomLog ${APACHE_LOG_DIR}/crumbforest_access.log combined

    # PHP Settings (optional)
    php_value upload_max_filesize 10M
    php_value post_max_size 12M
    php_value memory_limit 256M
</VirtualHost>

2. Site aktivieren

# Default Site deaktivieren (optional)
sudo a2dissite 000-default.conf

# CrumbForest aktivieren
sudo a2ensite crumbforest.conf

# Config testen
sudo apache2ctl configtest

# Apache neu starten
sudo systemctl restart apache2

🔒 SSL/HTTPS Setup (Let's Encrypt)

Certbot installieren

# Certbot installieren
sudo apt install certbot python3-certbot-apache -y

# Automatisches SSL Setup
sudo certbot --apache -d your-domain.com -d www.your-domain.com

# Folge den Prompts:
# - Email eingeben
# - Terms akzeptieren
# - Redirect HTTP → HTTPS: YES

Auto-Renewal aktivieren:

# Certbot timer prüfen
sudo systemctl status certbot.timer

# Manueller Renewal-Test
sudo certbot renew --dry-run

✅ Validierung

1. System-Checks

# Apache läuft?
sudo systemctl status apache2

# MariaDB läuft?
sudo systemctl status mariadb

# PHP Version
php -v

# Composer
composer --version

2. Datenbank-Test

mysql -u crumbforest_user -p crumbforest -e "SELECT 'OK' as status;"

3. API Health-Check

curl http://localhost/api/health
# Sollte: {"status":"ok","service":"crumbforest-php"}

4. PHPUnit Tests

cd /var/www/crumbforest

# Unit Tests (kein DB nötig)
./vendor/bin/phpunit --testsuite Unit

# Integration Tests (mit DB)
./vendor/bin/phpunit --testsuite Integration

# Alle Tests
./vendor/bin/phpunit

🔥 Firewall Setup

UFW (Uncomplicated Firewall)

# UFW installieren (falls nicht vorhanden)
sudo apt install ufw -y

# Default Policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Wichtige Ports öffnen
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS

# Firewall aktivieren
sudo ufw enable

# Status prüfen
sudo ufw status verbose

🐛 Troubleshooting

Apache startet nicht

# Logs prüfen
sudo tail -f /var/log/apache2/error.log
sudo tail -f /var/log/apache2/crumbforest_error.log

# Config testen
sudo apache2ctl configtest

# Port-Konflikte prüfen
sudo netstat -tlnp | grep :80

PHP Module fehlen

# Installierte Module prüfen
php -m

# Fehlende Module installieren
sudo apt install php-MODUL_NAME
sudo systemctl restart apache2

Database Connection Failed

# MariaDB läuft?
sudo systemctl status mariadb

# Credentials testen
mysql -u crumbforest_user -p crumbforest

# .env Permissions
ls -la /var/www/crumbforest/.env
# Sollte: -rw------- www-data www-data

Permission Denied

# Alle Permissions neu setzen
sudo chown -R www-data:www-data /var/www/crumbforest
sudo chmod -R 755 /var/www/crumbforest
sudo chmod -R 775 /var/www/crumbforest/logs
sudo chmod -R 775 /var/www/crumbforest/web_root/uploads
sudo chmod 600 /var/www/crumbforest/.env

500 Internal Server Error

# Apache Error Log
sudo tail -50 /var/log/apache2/crumbforest_error.log

# PHP Error Log
sudo tail -50 /var/www/crumbforest/logs/crumbforest.log

# SELinux prüfen (falls aktiv)
getenforce
# Falls "Enforcing": sudo setenforce 0

🔧 Wartung

Backups

# Database Backup
mysqldump -u crumbforest_user -p crumbforest | gzip > /backup/crumbforest_$(date +%Y%m%d).sql.gz

# File Backup
tar -czf /backup/crumbforest_files_$(date +%Y%m%d).tar.gz /var/www/crumbforest/web_root/uploads/

# Backup Cronjob (täglich um 2 Uhr)
sudo crontab -e
# Einfügen:
0 2 * * * mysqldump -u crumbforest_user -pPASSWORD crumbforest | gzip > /backup/crumbforest_$(date +\%Y\%m\%d).sql.gz

Updates

# System Updates
sudo apt update && sudo apt upgrade -y

# Composer Dependencies
cd /var/www/crumbforest
sudo composer update

# Apache restart
sudo systemctl restart apache2

Logs rotieren

# Logrotate Config
sudo nano /etc/logrotate.d/crumbforest

# Inhalt:
/var/www/crumbforest/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
}

📊 Monitoring (Optional)

Einfaches Health-Check Script

#!/bin/bash
# /usr/local/bin/crumbforest-health.sh

URL="http://localhost/api/health"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $URL)

if [ $RESPONSE -eq 200 ]; then
    echo "✅ CrumbForest is healthy"
    exit 0
else
    echo "❌ CrumbForest is down (HTTP $RESPONSE)"
    exit 1
fi

# Cronjob: Jede 5 Minuten checken
# */5 * * * * /usr/local/bin/crumbforest-health.sh >> /var/log/crumbforest-health.log 2>&1

🎯 Production Checklist

[ ] SSL/HTTPS aktiviert (Let's Encrypt)
[ ] Firewall konfiguriert (UFW)
[ ] .env hat 600 Permissions
[ ] JWT_SECRET ist zufälliger String (nicht Default!)
[ ] Database Backups eingerichtet
[ ] Logrotate konfiguriert
[ ] Default Admin-Passwort geändert
[ ] Monitoring/Health-Checks aktiv
[ ] fail2ban installiert (optional)
[ ] Automatische Updates konfiguriert

📝 Nützliche Commands

# Services
sudo systemctl status apache2
sudo systemctl restart apache2
sudo systemctl status mariadb
sudo systemctl restart mariadb

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

# Database
mysql -u crumbforest_user -p crumbforest

# Tests
cd /var/www/crumbforest && ./vendor/bin/phpunit

# Permissions Fix
sudo chown -R www-data:www-data /var/www/crumbforest

🆘 Support

Bei Problemen:
1. Apache Error Log prüfen
2. PHP Error Log prüfen
3. Permissions prüfen (www-data)
4. Database Connection testen
5. PHPUnit Tests laufen lassen

CrumbForest Scanner - Debian/Ubuntu Production Setup
Version: v1.0-RC1
Build: 2025-12-20

🐧 Der Pinguin atmet. Die Eule testet. Production läuft.