Ein geklontes Projekt liegt unter ~/Documents/MainPath/<organisations-slug>/<projekt-slug>/ mit einem Ordner pro Repository; ein Symlink auf local-configuration legt .vscode daneben. Öffne im Editor den Projektordner statt eines einzelnen Repositories; im Remote-Workspace ist das Layout identisch.
Anwendungen starten
Jede Anwendung startet im Root ihres Repositories mit demselben Befehl:
mp run-local
Ein Backend startet Docker-Dienste und Dev-Server, eine App Flutter Web oder den Dev-Server ihres Stacks, eine Homepage Hugo oder Astro, jeweils mit den Env-Dateien und auf festen Ports (mp ports). Bei Flutter gibst du Ziel und Gerät an, etwa mp run-local chrome; --env dev lädt die Dev-Konfiguration statt der lokalen, und der Start-Button von MainPath-Extension führt denselben Befehl aus, siehe Anwendungen starten.
Runtimes über asdf
Die Runtime-Versionen stehen pro Repository in .tool-versions; asdf verwaltet sie auf macOS und Linux, auf Windows FVM, NVM und HVM. mp bootstrap installiert sie ohne Start der Anwendung, mp doctor zeigt fehlende Werkzeuge. Installiere Runtimes nicht global am Projekt vorbei, sonst baut deine Maschine anders als die Pipeline.
Generierte und eigene Dateien
MainPath schreibt env/*.generated.env und .gitlab-ci.yml und überschreibt sie bei Änderungen am Projekt; deine Werte kommen in env/*.custom.env, danach startest du mp run-local neu. Ein Pre-Commit-Hook (mp git pre-commit check) aus MainPath Toolbox und clone blockiert Commits an den generierten Dateien; die Dateien im Einzelnen und gitops-configuration für Dev und Prod stehen unter Umgebungsvariablen. Passwörter, Tokens und Schlüssel verwaltet MainPath verschlüsselt; sie gehören nicht in *.custom.env, Commits, Logs oder Chat-Antworten.
Uploads im Backend
Persistente Datei-Uploads speichert ein Backend lokal unter ./upload und im Container unter /app/upload, wohin der Server ./backend-uploads mountet; Multer, FastAPI-Upload-Handler oder Laravel Storage zeigen dorthin und nicht auf user-uploads oder /app/uploads. Dockerfiles legen den Ordner mit RUN mkdir -p upload an.
Regeln für KI-Agenten
Das Agent-Plugin (mp agent install) fasst diese Regeln zusammen und verlangt, im passenden App-Repository statt in local-configuration zu arbeiten. Eigene Regeln ergänzt du in einer AGENTS.md im Anwendungs-Repository (Eigene Regeln für KI-Agenten); was die Pipeline nach dem Push macht, steht unter Git-Workflow und Deployment.