New Semantics

English

Deutsch

English

Deutsch

Theme

Installation ​

Step-by-step guide to get newmeta running locally. By the end, the PHP backend runs on Apache and the Nuxt dev server serves on http://localhost:3000.

System requirements ​

ComponentMinimumRecommended
PHP8.18.2+ with CLI and apcu
MySQL / MariaDBMySQL 5.7 / MariaDB 10.3MySQL 8 / MariaDB 10.6
Apache2.4 with mod_rewrite2.4
Node.js1820 LTS or newer
npm910+

You also need the PHP extensions pdo_mysql, mbstring, json, curl, gd, fileinfo, and openssl. APCu is optional but strongly recommended for the rate limiter and response cache.

Claude Code skills

The project ships with its own skills. When you work on the backend, php-backend-check, pagebuilder-dev, and NewSemantics-Backend-Layout load automatically — no configuration required.

1. Clone the repository ​

bash
git clone <repository-url> newmeta
cd newmeta

The repo is a monorepo — PHP backend, Nuxt frontend, docs, migrations, and CLI tools all live in a single checkout. See Directory Structure for details.

2. Set up the database ​

Create an empty database:

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

The schema is then built by the MigrationRunner — either automatically on the first call to /admin/update (Update Manager UI), or via CLI:

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

The runner scans _migrations/core/, _migrations/plugins/, and each plugin's own migrations/ directory, applying every file in order. Each migration is logged with a checksum in the _migrations table — re-runs are idempotent. See Plugins › Migrations for details.

Customer installs with demo data

Update-server ZIPs may ship with an SQL dump containing demo content (pages, shop products, e-learning courses). Import the dump before the first call to /admin — the MigrationRunner then only applies any missing schema changes on top.

3. PHP configuration ​

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

In config.local.php, fill in DB credentials and — if available — the update-server credentials:

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 is in .gitignore — never commit it. See Configuration for details.

4. Apache vhost ​

newmeta requires mod_rewrite for URL routing (/{view}/{item}/{child}/{value}/{add} is forwarded to index.php). Example vhost for local development:

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

After reloading Apache, the backend is reachable at http://newmeta.local/admin.

5. Install frontend dependencies ​

bash
cd _theme/vue-base
npm install

Optionally, create a .env to set the API and site URLs (the defaults are fine for local development):

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, not a production secret

NUXT_API_KEY=123456 is a placeholder for local development. In production, set a unique, random key — see Configuration › API keys.

All env variables are documented in Configuration › .env files.

6. Start the dev server ​

bash
npm run dev
  • Nuxt dev server: http://localhost:3000
  • Admin backend (through Apache): http://newmeta.local/admin

Hot reload is active for all Vue components, LESS files, and plugin layouts.

7. First admin login ​

On the first login, the TOTP 2FA setup wizard is enforced — 2FA is mandatory and cannot be disabled. Any authenticator app works (Google Authenticator, 1Password, Bitwarden, Authy, …).

Creating an admin user

On an empty DB without a demo dump, no admin exists yet. You can create an initial user via the setup wizard in the backend (on first page access), or by directly running INSERT on users with the rights field set. A full admin-operations guide is coming later.

2FA is mandatory

2FA cannot be bypassed or turned off. If the second factor is lost, you need the 8 one-time recovery codes shown during setup. Store the recovery codes safely.

8. Production build ​

For deployment, compile the Nuxt theme:

bash
cd _theme/vue-base
npm run build

The build runs LESS compilation, PurgeCSS, and ESBuild minification. Project-specific safelist extensions (e.g. dynamically generated classes) can be set via NUXT_PURGECSS_SAFELIST_* without touching nuxt.config.ts — see Configuration.

Common issues ​

.htaccess has no effect

If calls to /admin return 404, mod_rewrite or AllowOverride All is missing from the vhost. Check with apachectl -M | grep rewrite.

Session breaks after IP change

Sessions are IP-bound. When switching VPNs or between local IPs (IPv4/IPv6), the session is invalidated — just log in again.

CORS: 403 on API calls from Nuxt

Only the site's own domain is allowed by default. Additional origins (e.g. http://localhost:3000) are managed in the backend under /admin/api-keys → "Allowed Origins" — see Configuration › CORS.

See also ​