Installation

Table of contents | Inhaltsverzeichnis#

• Overview
• Requirements
• Target layout
• Database
• Configuration
• File permissions
• Web server
• First start
• Production checklist
• Troubleshooting

---

Overview | Überblick#

English

Two practical install paths exist:

1. Web installer via CMS/install.php
   The installer checks PHP compatibility, PDO MySQL availability, and write access for CMS/config/app.php. It collects database, site, and admin data, writes CMS/config/app.php, creates the schema through CMS\SchemaManager (SCHEMA_VERSION = v22), and creates the first administrator.
2. Repository checkout / manual setup
   Edit CMS/config/app.php directly. Replace every placeholder and every security key.

The installer is the preferred path for a fresh deployment. After a successful install, remove install.php from public deployments or keep it reachable only for administrators.

CMS/config.php is a stub. It sets ABSPATH, enforces PHP 8.4.0+, and loads CMS/config/app.php. If config/app.php is missing, the stub sends the visitor to the installer.

The installer session cookie uses HttpOnly, SameSite=Strict, and Secure when HTTPS is detected. Forms use a CSRF token. The admin password help text requires at least 12 characters.

On an existing install the welcome step can run a schema repair / update without wiping data, or a full reinstall that deletes all database tables.

Deutsch

Für neue Installationen gibt es zwei praktikable Wege:

1. Web-Installer über CMS/install.php
   Der Installer prüft PHP-Kompatibilität, PDO-MySQL und Schreibrechte für CMS/config/app.php. Er fragt Datenbank-, Site- und Admin-Daten ab, schreibt CMS/config/app.php, erstellt das Schema über CMS\SchemaManager (SCHEMA_VERSION = v22) und legt den ersten Administrator an.
2. Repository-Checkout / manuelle Einrichtung
   CMS/config/app.php direkt bearbeiten. Alle Platzhalterwerte und Security-Keys müssen ersetzt werden.

Der bevorzugte Einstieg für frische Deployments ist der Installer. Nach erfolgreicher Installation sollte install.php aus öffentlichen Deployments entfernt oder nur für Administratoren erreichbar gehalten werden.

CMS/config.php ist ein Stub. Er setzt ABSPATH, erzwingt PHP 8.4.0+ und lädt CMS/config/app.php. Fehlt config/app.php, leitet der Stub zum Installer weiter.

Die Installer-Session nutzt HttpOnly, SameSite=Strict und bei HTTPS zusätzlich Secure. Formulare sind CSRF-geschützt. Der Installer verlangt laut Hilfetext mindestens 12 Zeichen für das Admin-Passwort.

Bei einer bestehenden Installation kann der Willkommensschritt ein Schema-Update ohne Datenverlust oder eine Komplett-Neuinstallation mit Löschen aller Tabellen anbieten.

---

Requirements | Systemvoraussetzungen#

English

Enforced in code (CMS_MIN_PHP_VERSION in CMS/config.php): PHP 8.4.0+. Below that, config.php, installer, and bootstrap block a normal start.

The installer welcome screen checks:

• PHP version ≥ required version
• MySQL PDO extension (pdo_mysql)
• write permission so config/app.php can be created

The installer does not encode a MySQL/MariaDB version gate. Database access is PDO MySQL (mysql:host=…;dbname=…;charset=utf8mb4).

CMS/README.md documents MySQL 8.0+ / MariaDB 10.6+. The repository root README documents MySQL 5.7+ / MariaDB 10.3+. Treat those as documentation statements, not installer checks.

Deutsch

Im Code erzwungen (CMS_MIN_PHP_VERSION in CMS/config.php): PHP 8.4.0+. Darunter blockieren config.php, Installer und Bootstrap den normalen Start.

Der Installer-Willkommensbildschirm prüft:

• PHP-Version ≥ erforderliche Version
• MySQL-PDO-Erweiterung (pdo_mysql)
• Schreibrecht, damit config/app.php erzeugt werden kann

Der Installer prüft keine MySQL-/MariaDB-Versionsnummer. Der Datenbankzugriff läuft über PDO MySQL (mysql:host=…;dbname=…;charset=utf8mb4).

CMS/README.md nennt MySQL 8.0+ / MariaDB 10.6+. Das Root-README nennt MySQL 5.7+ / MariaDB 10.3+. Das sind Dokumentationsangaben, keine Installer-Gates.

---

Target layout | Zielstruktur beim Deployment#

English

In production the contents of CMS/ are typically the web root.

Deutsch

In produktiven Installationen ist in der Regel der Inhalt von CMS/ das Webroot.

---

Database | Datenbank anlegen#

English

Create an empty UTF-8 database, then let the installer or SchemaManager create tables.

CREATE DATABASE cms365 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'cms365user'@'localhost' IDENTIFIED BY 'SICHERES_PASSWORT';
GRANT ALL PRIVILEGES ON cms365.* TO 'cms365user'@'localhost';
FLUSH PRIVILEGES;

Core tables are created with CREATE TABLE IF NOT EXISTS by CMS\SchemaManager. Default table prefix is cms_ (DB_PREFIX). Default charset is utf8mb4 (DB_CHARSET).

The installer can also run a schema repair on an existing database without deleting content.

Deutsch

Eine leere UTF-8-Datenbank anlegen. Tabellen erzeugt anschließend der Installer bzw. SchemaManager.

CREATE DATABASE cms365 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'cms365user'@'localhost' IDENTIFIED BY 'SICHERES_PASSWORT';
GRANT ALL PRIVILEGES ON cms365.* TO 'cms365user'@'localhost';
FLUSH PRIVILEGES;

Die Kern-Tabellen werden mit CREATE TABLE IF NOT EXISTS durch CMS\SchemaManager angelegt. Standardpräfix ist cms_ (DB_PREFIX). Standardzeichensatz ist utf8mb4 (DB_CHARSET).

Der Installer kann auf einer bestehenden Datenbank auch eine Schema-Reparatur ohne Inhaltslöschung ausführen.

---

Configuration | Konfiguration in CMS/config/app.php#

English

CMS/config/app.php is a template with placeholders. install.php is supposed to overwrite it with real values and keys from random_bytes(32). Do not commit real credentials.

If you configure by hand, replace every placeholder.

Example for a key:

bin2hex(random_bytes(32))

Timezone in the template is Europe/Berlin.

Deutsch

CMS/config/app.php ist ein Template mit Platzhaltern. install.php soll die Datei mit echten Werten und Keys aus random_bytes(32) überschreiben. Keine echten Credentials committen.

Bei manueller Einrichtung alle Platzhalter ersetzen.

Beispiel für einen Key:

bin2hex(random_bytes(32))

Zeitzone im Template: Europe/Berlin.

---

File permissions | Dateirechte#

English

Do not use 777 in production.

Deutsch

Keine pauschalen 777-Rechte in Produktion.

---

Web server | Webserver konfigurieren#

English

Apache#

Requirements:

• mod_rewrite enabled
• AllowOverride All for the web root
• directory indexes disabled

Shipped CMS/.htaccess does not use <Directory> blocks (invalid in .htaccess). Private runtime paths (config/, core/, logs/, backups/, cache/) and installer internals are covered by rewrite / files rules. php_value limits apply only under mod_php; with PHP-FPM/CGI set upload limits in php.ini, the pool, or the hosting panel.

The private cache area stays blocked except public CSS/JS produced by AssetOptimizerService under cache/optimized-assets/<hash>.min.css and cache/optimized-assets/<hash>.min.js.

Public uploads remain direct URLs. .htaccess blocks executable uploads and hidden files, but allows normal files under uploads/. Local FontManager fonts under uploads/fonts/ set WOFF/WOFF2/TTF/OTF MIME types so browsers load them with X-Content-Type-Options: nosniff.

Nginx#

Unknown paths must reach index.php:

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

Do not serve config/, logs/, cache/, backups/, or core/ as static files.

Deutsch

Apache#

Voraussetzungen:

• mod_rewrite aktiv
• AllowOverride All für das Webroot
• Verzeichnisindexe deaktiviert

Die ausgelieferte CMS/.htaccess nutzt keine <Directory>-Blöcke (im .htaccess-Kontext unzulässig). Private Runtime-Pfade (config/, core/, logs/, backups/, cache/) und Installer-Interna werden über Rewrite-/Files-Regeln geschützt. php_value-Limits gelten nur unter mod_php; bei PHP-FPM/CGI müssen Upload-Limits in php.ini, Pool-Config oder Hosting-Panel gesetzt werden.

Der private Cache bleibt gesperrt, ausgenommen öffentliche CSS-/JS-Dateien von AssetOptimizerService unter cache/optimized-assets/<hash>.min.css und cache/optimized-assets/<hash>.min.js.

Öffentliche Uploads bleiben direkte URLs. Die .htaccess blockiert ausführbare Uploads und versteckte Dateien, lässt normale Dateien unter uploads/ aber durch. Für lokale FontManager-Schriften unter uploads/fonts/ werden WOFF/WOFF2/TTF/OTF-MIME-Typen gesetzt, damit Browser sie auch mit X-Content-Type-Options: nosniff laden.

Nginx#

Unbekannte Pfade müssen bei index.php landen:

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

config/, logs/, cache/, backups/ und core/ nicht als statische Dateien ausliefern.

---

First start | Erster Start#

English

After configuration:

1. Open the production SITE_URL
2. 365CMS loads CMS/config.php
3. The stub loads CMS/config/app.php
4. CMS\Bootstrap detects mode (web / admin / api / cli) and initializes services and routing
5. CMS\Database and CMS\SchemaManager create the base schema (v22) if needed
6. If you used the installer, the first admin account is created in the installer (step 4 of 5)

Change the first admin password immediately after install.

Deutsch

Nach korrekter Konfiguration:

1. Browser auf die produktive SITE_URL öffnen
2. 365CMS lädt CMS/config.php
3. Der Stub lädt CMS/config/app.php
4. CMS\Bootstrap erkennt den Modus (web / admin / api / cli) und initialisiert Services und Routing
5. CMS\Database und CMS\SchemaManager legen bei Bedarf das Basisschema (v22) an
6. Beim Installer wird das erste Admin-Konto im Installer angelegt (Schritt 4 von 5)

Das erste Admin-Passwort nach der Installation sofort ändern.

---

Production checklist | Produktions-Checkliste#

English

• [ ] All placeholders in CMS/config/app.php replaced
• [ ] Strong AUTH_KEY / SECURE_AUTH_KEY / NONCE_KEY
• [ ] CMS_DEBUG is false
• [ ] HTTPS active
• [ ] SITE_URL has no trailing slash and no subdirectory
• [ ] config/, logs/, cache/, backups/, core/ not publicly readable
• [ ] First admin password changed (minimum 12 characters at install time)
• [ ] install.php removed or locked down
• [ ] Backups scheduled
• [ ] Write access limited to logs/, cache/, uploads/, backups/

Deutsch

• [ ] Platzhalter in CMS/config/app.php vollständig ersetzt
• [ ] starke AUTH_KEY / SECURE_AUTH_KEY / NONCE_KEY
• [ ] CMS_DEBUG ist false
• [ ] HTTPS aktiv
• [ ] SITE_URL ohne Trailing Slash und ohne Unterverzeichnis
• [ ] config/, logs/, cache/, backups/, core/ nicht öffentlich lesbar
• [ ] erstes Admin-Passwort geändert (Installer: mindestens 12 Zeichen)
• [ ] install.php entfernt oder abgesichert
• [ ] regelmäßige Backups eingerichtet
• [ ] Schreibrechte auf logs/, cache/, uploads/, backups/ begrenzt

---

Troubleshooting#

English

Redirect to installer or configuration#

Usually CMS/config/app.php is missing or still contains placeholders such as YOUR_DATABASE_USER.

Database connection fails#

Check DB_HOST, DB_NAME, DB_USER, DB_PASS, user grants, and database reachability.

Pretty URLs do not work#

Check Apache rewrite or Nginx try_files, the web root, and SITE_URL (no typo, no trailing slash, no subdirectory).

Admin loads but features are missing#

Typical causes: missing PHP extensions (curl, zip, gd), directories that are not writable (cache, logs, backups, uploads), or a schema that was not migrated to v22.

Further reading:

• System architecture
• Database schema
• System & monitoring

Deutsch

Weiterleitung auf Installer oder Konfiguration#

Meist fehlt CMS/config/app.php oder enthält noch Platzhalter wie YOUR_DATABASE_USER.

Datenbankverbindung schlägt fehl#

DB_HOST, DB_NAME, DB_USER, DB_PASS, Rechte des Datenbankbenutzers und Erreichbarkeit prüfen.

Pretty URLs funktionieren nicht#

Apache-Rewrite bzw. Nginx-try_files, korrektes Webroot und SITE_URL prüfen (kein Tippfehler, kein Trailing Slash, kein Unterverzeichnis).

Admin lädt, aber Teilfunktionen fehlen#

Typische Ursachen: fehlende PHP-Erweiterungen (curl, zip, gd), nicht beschreibbare Verzeichnisse (cache, logs, backups, uploads) oder ein nicht auf v22 migriertes Schema.

Weiterführend:

• Systemarchitektur
• Datenbank-Schema
• System & Monitoring

---

Ergänzung (Stand 2026-10-02)#

• Konfigurationsreihenfolge: CMS/index.php lädt config/app.php vor config.php. Eigene Konstanten (z. B. JWT_SECRET, Debug-Schalter) gehören deshalb in config/app.php; nach jedem erneuten Installer-Lauf prüfen, ob sie erhalten geblieben sind (siehe core/STATUS.md).
• Installer-Sperre: Existiert bereits eine Konfiguration, schreibt der Installer eine Lock-Datei und beantwortet weitere Aufrufe mit HTTP 403 („blocked“). install.php trotzdem nach der Installation entfernen oder per Webserver sperren.
• Mindest-PHP: CMS_MIN_PHP_VERSION = 8.4.0 (Prüfung im Willkommensschritt).
• Cron: php CMS/cron.php --task=all (CLI) oder HTTP-Aufruf mit Token (?token=…&task=…); Tasks all, mail-queue, hourly, daily, feeds, cms_cron_*. Details: admin/system-settings/SYSTEM.md.
• Nach der Installation: Mailversand testen (admin/system-settings/MAIL.md), erstes Backup anlegen (admin/system-settings/BACKUP.md), Sicherheits-Audit ausführen (admin/security/SECURITY-AUDIT.md).
• Updates und Deployments: workflow/UPDATE-DEPLOYMENT-WORKFLOW.md.