Deployment — docs.new-semantics.com

Anleitung für das Setup und den laufenden Deploy der newmeta-Doku.

Ziel-Domain: docs.new-semantics.comStatus: Öffentlich zugänglich — keine Basic-Auth, Crawler werden via robots.txt + Sitemap eingeladen. Produktive Webserver-Config: nginx-plesk.conf (Plesk-Zusatz-Direktiven)

0. Config-Übersicht

Im Verzeichnis docs/deploy/ liegen zwei nginx-Configs für unterschiedliche Hosting-Szenarien:

Datei	Einsatz	Aktuell produktiv?
`nginx-plesk.conf`	Plesk-Hosting (Zusatz-Direktiven)	Ja
`nginx-standalone.conf`	nginx direkt als primärer Webserver (eigene VM, Dedicated, Docker)	Nein — Alternative für Nicht-Plesk-Setups

Beide Configs sind public-ready: keine Basic-Auth, kein X-Robots-Tag: noindex, Security-Header bleiben aktiv.

1. Plesk-Setup (aktuell produktiv)

1.1 Subdomain + SSL

Plesk → Domains → Add Subdomain → docs.new-semantics.com
Document-Root auf das Verzeichnis setzen, in das später dist/ rsynct wird (z.B. httpdocs/)
SSL/TLS → Let's Encrypt aktivieren (inkl. Auto-Renewal)
Apache & nginx Settings → Proxy mode DEAKTIVIEREN (nginx serviert direkt, kein Apache-Fallback)

1.2 nginx-Direktiven einbinden

Im gleichen Panel: „Additional nginx directives" → Inhalt von docs/deploy/nginx-plesk.conf einfügen und speichern. Plesk umgibt den Inhalt automatisch mit dem server{}-Block.

1.3 Verify

bash

curl -I https://docs.new-semantics.com/
# HTTP/2 200
# server: nginx
# x-content-type-options: nosniff
# (kein x-robots-tag mehr)

2. Standalone-Setup (Alternative, ohne Plesk)

Für Deployments, bei denen nginx direkt läuft (eigene VM, Docker, Dedicated):

bash

sudo cp docs/deploy/nginx-standalone.conf \
        /etc/nginx/sites-available/docs.new-semantics.conf
sudo ln -s /etc/nginx/sites-available/docs.new-semantics.conf /etc/nginx/sites-enabled/

sudo certbot --nginx -d docs.new-semantics.com
sudo nginx -t && sudo systemctl reload nginx

Details siehe Kommentare oben in nginx-standalone.conf.

3. Laufender Deploy per rsync

3.1 Voraussetzungen lokal

Node 20+
PHP ≥ 8.2 (für build:openapi via swagger-php)
optional librsvg2-bin / ImageMagick (für build:og SVG→PNG)

3.2 Build + Deploy

bash

cd docs
npm ci
npm run build:openapi    # public/openapi.json aus swagger-php
npm run build:og         # public/og-image.svg → og-image.png (optional)
npm run build            # VitePress → .vitepress/dist/

# Pre-Deploy-Backup (empfohlen)
ssh [email protected] \
  "sudo cp -a /var/www/docs.new-semantics.com \
             /var/www/docs.new-semantics.com.bak-$(date +%Y%m%d-%H%M)"

# Deploy
rsync -avz --delete \
  .vitepress/dist/ \
  [email protected]:/var/www/docs.new-semantics.com/

--delete entfernt Remote-Files, die lokal nicht mehr existieren.

4. GitHub-Actions-Deploy (optional)

Beispiel-Workflow .github/workflows/deploy-docs.yml:

yaml

name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '_core/system/api/**'
      - '_public/extensions/core/backend/**'
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: docs/package-lock.json

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      - name: Install rsvg (für OG-Image)
        run: sudo apt-get update && sudo apt-get install -y librsvg2-bin

      - name: Install
        working-directory: docs
        run: npm ci

      - name: Generate OpenAPI
        working-directory: docs
        run: npm run build:openapi

      - name: Generate OG-Image
        working-directory: docs
        run: npm run build:og

      - name: Build
        working-directory: docs
        run: npm run build

      - name: Pre-Deploy Backup
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          script: |
            sudo cp -a /var/www/docs.new-semantics.com \
                      /var/www/docs.new-semantics.com.bak-$(date +%Y%m%d-%H%M) || true

      - name: Deploy via rsync
        uses: burnett01/[email protected]
        with:
          switches: -avz --delete
          path: docs/.vitepress/dist/
          remote_path: /var/www/docs.new-semantics.com/
          remote_host: ${{ secrets.DEPLOY_HOST }}
          remote_user: ${{ secrets.DEPLOY_USER }}
          remote_key: ${{ secrets.DEPLOY_KEY }}

Secrets: DEPLOY_HOST, DEPLOY_USER, DEPLOY_KEY (SSH-Private-Key des Deploy-Accounts).

5. Public-Launch-Checkliste

Beim Launch wurden folgende Dinge aktiviert/deaktiviert:

noindex, nofollow aus docs/.vitepress/config.ts entfernt
X-Robots-Tag: noindex, nofollow aus nginx-plesk.conf + nginx-standalone.conf entfernt
<meta name="robots" content="noindex, nofollow"> aus docs/public/scalar.html entfernt
docs/public/robots.txt angelegt (Allow: / + Sitemap-Verweis)
VitePress-sitemap-Option aktiviert (hostname: https://docs.new-semantics.com) — Build erzeugt dist/sitemap.xml mit hreflang-Tags für alle Locales
HTTP Basic Auth (.htpasswd) komplett entfernt
scalar.html auf Englisch (lang="en", UI-Texte)

Post-Launch-Verifikation:

bash

# Sitemap erreichbar?
curl https://docs.new-semantics.com/sitemap.xml | head -20

# robots.txt erreichbar?
curl https://docs.new-semantics.com/robots.txt

# hreflang in HTML?
curl -s https://docs.new-semantics.com/ | grep hreflang
# → sollte <link rel="alternate" hreflang="de" ...> enthalten

6. Analytics nachrüsten (optional)

Aktuell ist kein Tracking aktiv. Wer später Analytics will, empfohlen: Plausible (DSGVO-freundlich, kein Cookie-Banner nötig, Daten in der EU).

6.1 Plausible (empfohlen)

In docs/.vitepress/config.ts im head-Array ergänzen:

head: [
  // ... bestehende Tags ...
  ['script', {
    defer: '',
    'data-domain': 'docs.new-semantics.com',
    src: 'https://plausible.io/js/script.js',
  }],
],

Danach unter plausible.io die Domain hinzufügen. Plausible setzt keine Cookies, trackt keine IPs und braucht daher kein Consent-Banner (TTDSG-konform — trotzdem kurz in die Datenschutzerklärung aufnehmen).

6.2 Matomo (self-hosted, falls eigene Infra)

Ähnlicher Ansatz, aber mit eigener Matomo-Instanz (Cloud oder self-hosted). Cookie-Banner kann je nach Konfiguration nötig werden (Anonymisierungs-Einstellungen prüfen).

6.3 Google Analytics 4

Nicht empfohlen (Cookie-Banner-Pflicht + Datenschutz-Fragen). Falls dennoch gewünscht: Standard-GA4-Snippet via head-Array, Consent Management nötig.

7. Build-Kennzahlen

Nach npm run build steht unter docs/.vitepress/dist/:

Output-Größe: ca. 8–12 MB (inkl. MiniSearch-Index, OpenAPI-Spec, Scalar-Bundle, Sitemap)
Build-Laufzeit: ca. 25–60 s auf moderner Hardware
Gzipped transferiert (nginx gzip aktiv): ca. 2–3 MB initial, danach per-Route-Lazy-Loading

8. Troubleshooting

Symptom	Wahrscheinliche Ursache	Fix
502/503 nach Deploy	nginx-Config-Syntaxfehler	`sudo nginx -t` ausführen
404 auf Sub-Seiten nach Reload	Clean-URL-Rewrite fehlt	Plesk-Zusatz-Direktiven aus `nginx-plesk.conf` aktiv?
Scalar lädt die API nicht	`openapi.json` nicht deployed oder 404	URL `/openapi.json` manuell aufrufen, DevTools prüfen
Sprachschalter fehlt	Locale-Config oder Build-Fehler	`locales`-Block in `config.ts` prüfen, `npm run build` neu laufen lassen
Alte Seiten nach Deploy sichtbar	HTML-Cache (`max-age=300` in nginx)	5 Min warten oder Hard-Reload
hreflang fehlt im `<head>`	i18n-Config fehlerhaft	`locales.root` + `locales.de` in `config.ts` prüfen — VitePress generiert hreflang automatisch

9. Rollback

bash

# Backup vor jedem Deploy (siehe Section 3)
sudo cp -a /var/www/docs.new-semantics.com /var/www/docs.new-semantics.com.bak-$(date +%Y%m%d-%H%M)

# Rollback: Backup-Verzeichnis zurück-movieren
sudo mv /var/www/docs.new-semantics.com /var/www/docs.new-semantics.com.broken
sudo mv /var/www/docs.new-semantics.com.bak-YYYYMMDD-HHMM /var/www/docs.new-semantics.com
sudo systemctl reload nginx

Für produktive Setups mit vielen Deploys: Symlink-Swap via Release-Verzeichnisse (/var/www/docs.new-semantics.com -> releases/20260420-1830/).

Deployment — docs.new-semantics.com ​

0. Config-Übersicht ​

1. Plesk-Setup (aktuell produktiv) ​

1.1 Subdomain + SSL ​

1.2 nginx-Direktiven einbinden ​

1.3 Verify ​

2. Standalone-Setup (Alternative, ohne Plesk) ​

3. Laufender Deploy per rsync ​

3.1 Voraussetzungen lokal ​

3.2 Build + Deploy ​

4. GitHub-Actions-Deploy (optional) ​

5. Public-Launch-Checkliste ​

6. Analytics nachrüsten (optional) ​

6.1 Plausible (empfohlen) ​

6.2 Matomo (self-hosted, falls eigene Infra) ​

6.3 Google Analytics 4 ​

7. Build-Kennzahlen ​

8. Troubleshooting ​

9. Rollback ​

Deployment — docs.new-semantics.com

0. Config-Übersicht

1. Plesk-Setup (aktuell produktiv)

1.1 Subdomain + SSL

1.2 nginx-Direktiven einbinden

1.3 Verify

2. Standalone-Setup (Alternative, ohne Plesk)

3. Laufender Deploy per rsync

3.1 Voraussetzungen lokal

3.2 Build + Deploy

4. GitHub-Actions-Deploy (optional)

5. Public-Launch-Checkliste

6. Analytics nachrüsten (optional)

6.1 Plausible (empfohlen)

6.2 Matomo (self-hosted, falls eigene Infra)

6.3 Google Analytics 4

7. Build-Kennzahlen

8. Troubleshooting

9. Rollback