socai Site Deployment

socai Site-Deployment

Verwende dieses Skill immer dann, wenn die Aufgabe die socai-Website-Bereitstellung, die Vercel-Konfiguration, socai.io, www.socai.io, /download, /github oder PR-Preview-Bereitstellungen betrifft.

Dieses Skill ist das verbindliche Runbook für die Bereitstellung. ../../../docs/website-deployment.md bleibt bewusst kurz und verweist hierher zurück, um doppelte Anweisungen zu vermeiden.

Projektkontext

• Quellcode der Website: site/
• Framework: Astro Static Site
• Vercel Team/Scope: socai-d83824c8 (socai)
• Vercel Projekt: socai-site
• Produktionsdomain: https://socai.io
• Dokumentationsroute: https://socai.io/docs/ (Starlight-Seiten, die mit der Astro-Site erstellt werden)
• Kanonischer Host: socai.io
• www-Verhalten: https://www.socai.io/* sollte 308/Redirect zu https://socai.io/*
• Download-Route: https://socai.io/download leitet weiter zum aktuellen universellen macOS-DMG auf dem socai OSS-Release-Mirror
• GitHub-Route: https://socai.io/github leitet weiter zu https://github.com/socai-io/socai

Erwartete Vercel-Projekteinstellungen:

Einstellung	Wert
Framework-Preset	Astro
Root-Verzeichnis	site
Installationsbefehl	pnpm install
Build-Befehl	pnpm build
Ausgabeverzeichnis	dist
Node.js-Version	24.x

Sicherheitsregeln

• Verwende den Scope socai-d83824c8 für alle Vercel-Projekt-/Domain-Befehle.
• Führe keine Bereitstellung vom falschen Vercel-Team oder einem persönlichen Projekt durch.
• Committe nicht site/.vercel/, site/dist/, site/.astro/ oder site/node_modules/.
• Aktiviere keine Analysen, es sei denn, der Benutzer stimmt ausdrücklich zu.
• Bearbeite keine App-Release-Assets, während du an der Website-Bereitstellung arbeitest.
• Behalte Issues in einem dedizierten Branch und öffne/aktualisiere einen PR für Repository-Änderungen.
• Wenn du temporär Vercel-Projekteinstellungen für eine manuelle Bereitstellung änderst, stelle sie vor dem Abschluss wieder her.

Lokale Validierung

Vor der Bereitstellung oder dem Öffnen eines PR für bereitstellungsbezogenen Code/Konfiguration:

cd site
pnpm install
pnpm build

Validiere JSON/XML-Konfiguration, wenn sie geändert wurde:

python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PY

Vercel-Status prüfen

vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8

Bestätige, dass die Projekteinstellungen das Root-Verzeichnis site, das Framework Astro, den Build-Befehl pnpm build, das Ausgabeverzeichnis dist und den Installationsbefehl pnpm install anzeigen.

Bevorzugte Produktionsbereitstellung

Bevorzugter Weg nach Aktivierung der Git-Integration:

1. Merge der Website-Änderungen in main.
2. Lasse Vercel das socai-site-Projekt aus dem Root-Verzeichnis site erstellen.
3. Überprüfe die Produktions-URLs mit den untenstehenden Befehlen.

PR-Previews erfordern ebenfalls eine verbundene Git-Integration im Vercel-Dashboard.

Notfall-/Manuelle CLI-Produktionsbereitstellung

Da das Vercel-Projekt mit dem Root-Verzeichnis site konfiguriert ist, kann eine direkte lokale Bereitstellung aus site/ mit site/site-Root-Verzeichnis-Fehlern fehlschlagen. Falls die Git-Integration nicht verfügbar ist und eine CLI-Bereitstellung erforderlich ist, verwende diesen temporären Root-Workaround und stelle das Root-Verzeichnis danach wieder her.

set -euo pipefail

cat > /tmp/vercel-root-null.json <<'EOF'
{
  "rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
  "rootDirectory": "site"
}
EOF

restore_root() {
  vercel api /v10/projects/socai-site \
    --scope socai-d83824c8 \
    -X PATCH \
    --input /tmp/vercel-root-site.json \
    --silent || true
}
trap restore_root EXIT

vercel api /v10/projects/socai-site \
  --scope socai-d83824c8 \
  -X PATCH \
  --input /tmp/vercel-root-null.json \
  --silent

cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yes

Nach der Bereitstellung bestätigen, dass das Root-Verzeichnis wiederhergestellt wurde:

vercel project inspect socai-site --scope socai-d83824c8 --yes

Belasse das Projekt nicht mit Root Directory . oder null; Git-Previews sind auf site angewiesen.

URL-Überprüfung

Verwende zuerst HEAD-Checks:

curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/github

Erwartetes Verhalten beim ersten Hop:

• https://socai.io/ gibt 200 zurück.
• https://socai.io/docs/ gibt 200 zurück, und eine verschachtelte Seite wie /docs/quickstart/ gibt 200 zurück.
• https://www.socai.io/ gibt 308 mit location: https://socai.io/ zurück.
• https://socai.io/sitemap.xml leitet dauerhaft zu /sitemap-index.xml weiter, das 200 zurückgibt.
• https://socai.io/download gibt eine Vercel-Weiterleitung (307) zurück zum aktuellen universellen macOS-DMG auf dem konfigurierten OSS-Release-Mirror.
• https://socai.io/github gibt eine Vercel-Weiterleitung (307) zu https://github.com/socai-io/socai zurück.

Verwende -L nur, wenn du der Kette folgen möchtest:

curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download

Git-Preview-Setup

Versuche:

cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8

Falls Vercel zurückgibt:

Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.

dann muss ein Vercel/GitHub-Kontoinhaber die GitHub-Anmeldung/Integration im Vercel-Dashboard verbinden und anschließend socai-site mit dem Root-Verzeichnis site mit socai-io/socai verbinden.

Fehlerbehebung

Website-Änderungen nach einem Multi-Commit-Push übersprungen

Der ignorierte Build-Schritt in site/vercel.json muss HEAD mit VERCEL_GIT_PREVIOUS_SHA (dem letzten erfolgreichen Deployment für dieses Projekt und diesen Branch) vergleichen, nicht mit HEAD^. Der letzte Commit in einem Push kann nur Rust-Code ändern, während frühere Commits die Website ändern. Wenn die vorherige Deployment-SHA fehlt oder im flachen Clone nicht verfügbar ist, baue, anstatt zu überspringen. Exit 0 überspringt einen Build; Exit 1 führt ihn aus.

Root Directory "site" does not exist

Dies tritt normalerweise auf, wenn eine lokale CLI-Bereitstellung von site/ ausgeführt wird, während das Remote-Projekt ebenfalls das Root-Verzeichnis site hat. Verwende den obigen Notfall-/manuellen CLI-Bereitstellungs-Workaround oder bevorzuge Git-Bereitstellungen.

Zu viele Dateien hochgeladen

Das Bereitstellen vom Repository-Root aus kann Rust/Python-Build-Artefakte enthalten und die Dateianzahl von Vercel überschreiten. Stelle das Repository-Root nicht direkt bereit, es sei denn, du hast eine getestete Ignorier-/Archivierungsstrategie. Bevorzuge Git-Bereitstellungen oder die Notfall-/manuelle Bereitstellung von site/ mit temporärem Root-Reset.

www.socai.io liefert 200 statt einer Weiterleitung

Stelle sicher, dass das neueste Produktions-Deployment die Host-Weiterleitung in site/vercel.json enthält, und stelle dann erneut bereit. Überprüfe mit:

curl -I https://www.socai.io/

GitHub-Latest-Release-Metadaten nicht verfügbar

Die Website sollte trotzdem einen generischen, nicht veralteten Text (latest release) anzeigen und /download sollte weiterhin zum neuesten Release-Asset von GitHub weiterleiten.

Rückmeldung

Wenn du über eine Bereitstellungsaufgabe berichtest, gib Folgendes an:

• Branch/PR, falls Repository-Dateien geändert wurden
• Bestätigte Vercel-Projekteinstellungen
• Bereitstellungs-URL und Produktionsdomain
• Ausgeführte Befehle
• Zusammenfassung der Überprüfungsausgabe für /, /docs/, /docs/quickstart/, www, /download und /github
• Alle verbleibenden manuellen Blockaden, insbesondere Git-Integration / PR-Previews