New Semantics

Deutsch

English

Deutsch

English

Theme

Installation ​

Schritt-fuer-Schritt-Anleitung, um New Semantics lokal in Betrieb zu nehmen. Am Ende laeuft der PHP-Backend unter Apache und der Nuxt-Dev-Server unter http://localhost:3000.

Systemvoraussetzungen ​

KomponenteMinimalEmpfohlen
PHP8.18.2+ mit CLI und apcu
MySQL / MariaDBMySQL 5.7 / MariaDB 10.3MySQL 8 / MariaDB 10.6
Apache2.4 mit mod_rewrite2.4
Node.js1820 LTS oder neuer
npm910+

Zusaetzlich werden die PHP-Extensions pdo_mysql, mbstring, json, curl, gd, fileinfo und openssl benoetigt. APCu ist optional, aber fuer Rate-Limiter und Response-Cache stark empfohlen.

Claude-Code-Skills

Das Projekt liefert eigene Skills mit. Beim Arbeiten am Backend laden sich php-backend-check, pagebuilder-dev und NewSemantics-Backend-Layout automatisch — keine Konfiguration noetig.

1. Repository klonen ​

bash
git clone <repository-url> newmeta
cd newmeta

Das Repo ist ein Monorepo — PHP-Backend, Nuxt-Frontend, Docs, Migrations und CLI-Tools liegen in einem einzigen Checkout. Details siehe Verzeichnisstruktur.

2. Datenbank einrichten ​

Leere Datenbank anlegen:

bash
mysql -u root -p -e "CREATE DATABASE newmeta CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

Das Schema wird danach ueber den MigrationRunner aufgebaut — entweder automatisch beim ersten Aufruf von /admin/update (Update-Manager-UI) oder ueber die CLI:

bash
php console/bin scheduled-tasks --time-limit=60

Der Runner scannt _migrations/core/, _migrations/plugins/ sowie die plugin-eigenen migrations/-Ordner und spielt alle Dateien in Reihenfolge ein. Jede Migration wird in der Tabelle _migrations mit Checksum protokolliert — erneute Laeufe sind idempotent. Details in Plugins › Migrations.

Kunden-Installationen mit Demodaten

Ausliefer-ZIPs des Update-Servers koennen einen SQL-Dump mit Demo-Inhalten (Seiten, Shop-Artikel, E-Learning-Kurse) enthalten. Den Dump vor dem ersten /admin-Aufruf einspielen — der MigrationRunner setzt danach nur noch fehlende Schema-Aenderungen auf.

3. PHP-Konfiguration ​

bash
cp config.local.example.php config.local.php

In config.local.php die DB-Zugangsdaten und — falls vorhanden — die Update-Server-Credentials eintragen:

php
<?php
$GLOBALS["db_host"] = "localhost";
$GLOBALS["db_user"] = "newmeta";
$GLOBALS["db_pw"]   = "********";
$GLOBALS["db_db"]   = "newmeta";

$GLOBALS["update_user"]     = "";
$GLOBALS["update_password"] = "";
$GLOBALS["update_base_url"] = "https://update.newmeta.de";

config.local.php ist in .gitignore — niemals committen. Details siehe Konfiguration.

4. Apache-Vhost ​

newmeta erwartet mod_rewrite fuer das URL-Routing (/{view}/{item}/{child}/{value}/{add} wird an index.php uebergeben). Beispiel-Vhost fuer die lokale Entwicklung:

apache
<VirtualHost *:80>
    ServerName newmeta.local
    DocumentRoot /pfad/zu/newmeta
    <Directory /pfad/zu/newmeta>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nach dem Reload ist das Backend unter http://newmeta.local/admin erreichbar.

5. Frontend-Abhaengigkeiten installieren ​

bash
cd _theme/vue-base
npm install

Optional .env anlegen, um API- und Site-URL zu setzen (Standardwerte reichen fuer die lokale Entwicklung):

bash
cat > .env <<'EOF'
NUXT_API_KEY=123456
NUXT_PUBLIC_API_BASE=http://newmeta.local/api
NUXT_PUBLIC_SITE_URL=http://newmeta.local
NUXT_PUBLIC_THEME=vue-base
EOF

Dev-Key, kein Produktions-Secret

NUXT_API_KEY=123456 ist ein Platzhalter fuer die lokale Entwicklung. Fuer Produktion einen eigenen, zufaelligen Key setzen — siehe Konfiguration › API-Keys.

Alle Env-Variablen sind in Konfiguration › .env-Dateien dokumentiert.

6. Dev-Server starten ​

bash
npm run dev
  • Nuxt-Dev-Server: http://localhost:3000
  • Admin-Backend (ueber Apache): http://newmeta.local/admin

Hot-Reload ist fuer alle Vue-Komponenten, LESS-Dateien und Plugin-Layouts aktiv.

7. Erster Admin-Login ​

Beim ersten Login wird der TOTP-2FA-Setup-Assistent erzwungen — 2FA ist verpflichtend und kann nicht deaktiviert werden. Jede Authenticator-App funktioniert (Google Authenticator, 1Password, Bitwarden, Authy, …).

Admin-User anlegen

Bei einer leeren DB ohne Demo-Dump existiert zunaechst kein Admin. Einen initialen User kann der Setup-Assistent im Backend anlegen (bei erstem Seiten-Aufruf) oder per direktem INSERT in users mit gesetztem rights-Feld. Eine dedizierte Admin-Bedienungs-Anleitung ist fuer zukuenftige Releases geplant.

2FA ist Pflicht

2FA laesst sich nicht umgehen oder abschalten. Bei Verlust des zweiten Faktors werden die 8 einmaligen Recovery-Codes benoetigt, die im Setup angezeigt werden. Recovery-Codes sicher aufbewahren.

8. Production-Build ​

Fuer ein Deployment wird das Nuxt-Theme kompiliert:

bash
cd _theme/vue-base
npm run build

Der Build laeuft durch LESS-Kompilierung, PurgeCSS und ESBuild-Minifizierung. Projektspezifische Safelist-Erweiterungen (z. B. dynamisch generierte Klassen) lassen sich via NUXT_PURGECSS_SAFELIST_* setzen, ohne nuxt.config.ts anzufassen — siehe Konfiguration.

Haeufige Fehler ​

.htaccess wirkt nicht

Wenn Aufrufe wie /admin einen 404 zurueckliefern, fehlt mod_rewrite oder AllowOverride All im Vhost. Pruefen mit apachectl -M | grep rewrite.

Session-Probleme nach IP-Wechsel

Sessions sind an die IP gebunden. Bei VPN-Wechseln oder zwischen lokalen IPs (IPv4/IPv6) wird die Session invalidiert — einmal neu einloggen.

CORS: 403 beim API-Call aus Nuxt

Nur die eigene Domain ist standardmaessig erlaubt. Zusaetzliche Origins (z. B. http://localhost:3000) werden im Backend unter /admin/api-keys → "Allowed Origins" gepflegt — siehe Konfiguration › CORS.

Siehe auch ​