diff --git a/.github/instructions/DOCS.instructions.md b/.github/instructions/DOCS.instructions.md index 2d2c86515..343a1c8af 100644 --- a/.github/instructions/DOCS.instructions.md +++ b/.github/instructions/DOCS.instructions.md @@ -15,6 +15,7 @@ Pay special attention to these guidelines when authoring and reviewing documenta - Markdown sub-headings within a document must have explicit anchor IDs for stable linking (this does not apply to the markdown front matter); suggest changes during code review if missing - Use the `` component for linking to API operations, and `` for including example requests. Do not link to API operations by hardcoding URLs or markdown links to the reference docs, as these are brittle and will break if the operation name or URL changes. +- **Dash usage:** Use hyphens (`-`) for compound words and ranges (e.g., "open-source", "2024-2025"). Use em dashes (`—`) for parenthetical asides and sentence breaks (e.g., "Deploy your app — with integrated tools — in minutes"). Use en dashes (`–`) sparingly, only for numeric ranges when em dash or hyphen is inappropriate. ## Security diff --git a/docs/guides/deployment/ai_developed_apps.mdx b/docs/guides/deployment/ai_developed_apps.mdx new file mode 100644 index 000000000..91395404a --- /dev/null +++ b/docs/guides/deployment/ai_developed_apps.mdx @@ -0,0 +1,197 @@ +--- +title: Deploying AI-developed apps +sidebar_label: AI-developed apps +tags: + - Deployment + - GitHub + - Apps +description: Structure and quickstart for shipping AI-developed apps with a zero-conf approach +--- + +## Introduction / Motivation {#introduction-motivation} + +With rapidly advancing AI-driven development tools, building applications has become more accessible than ever. +We want to make it as easy as possible to take the apps you create — whether prototyped quickly or developed thoughtfully — and ship them to the world with confidence. + +Besides rapid prototyping and development, we want to enable users to easily share their +AI-developed apps with others and deploy them to production environments without +needing to worry about complex deployment processes or configurations. + +Whether you're building a small business app or a more complex application using AI-driven development, this guide will help you get +your app from your local machine (or cloud-based IDE) to the world with minimal friction. + +Deploying an app is exciting — and worth doing thoughtfully. Compliance, privacy, security and operational +responsibility matter, and we recommend connecting with our community if you have questions. + +## AI-developed app landscape overview {#ai-developed-app-landscape-overview} + +Apps built through AI-driven development are easy to create, and deployment options vary widely. + +Different platforms offer different trade-offs. Vendors like Replit and Lovable prioritize developer speed +and ease of use with their specific project templates, build systems, and deployment pipelines. This convenience +comes with a trade-off: moving your app to another platform later may require rework. +On the other hand, you get a fast path to production with integrated tools and support. + +Platforms like GitHub and mittwald, however, offer more standard and flexible +deployment options that can be easily adapted to different environments. + +By using GitHub as a central repository for your AI-developed app, you can maintain +a clear history of changes, collaborate with others, and deploy to various platforms +without being tied to a specific vendor's ecosystem. + +This approach allows for greater freedom and control over your app's deployment +while still benefiting from the ease and speed that AI-driven development provides. + +## GitHub is our anchor {#github-is-our-anchor} + +If we can export to GitHub, we have good chances to deploy anywhere. + +Most platforms support GitHub as a source for deployment, and having a well-structured +GitHub repository allows for better collaboration, version control, and integration +with various deployment tools and services. If GitHub is not the Git platform of choice, +the same principles apply to any other Git hosting service that supports similar features. + +The moment we can export our AI-developed app to GitHub, we can leverage a wide range of +deployment options, including continuous integration and continuous deployment (CI/CD) +pipelines and containerization. + +Many tools offer two-way synchronization with GitHub, which means that changes made in +the GitHub repository can be automatically reflected in the deployment environment, +and vice versa. This allows for a more seamless development and deployment process, +as developers can work on their code in GitHub while still having the benefits +of a live deployment environment. + +## Principles and limits of zero-conf deployments {#principles-and-limits-of-zero-conf-deployments} + +:::warning +Export quality varies, so test locally first. A well-structured export that includes all necessary code, +configuration, and build files makes deployment and maintenance much easier. +A partial or incomplete export may require rework during deployment or maintenance, and can create +issues with version control and collaboration. +::: + +As most platforms deploy with custom pipelines and configurations, +we need to define a common denominator for zero-conf deployment. +In this context, zero-conf deployment means that we can take the exported code from GitHub +and deploy it to a platform without needing to make any manual changes or configurations. + +In other words: End users should be able to deploy their AI-developed app with minimal setup, +ideally just by connecting their GitHub repository to a deployment platform that supports +zero-conf deployment. + +Unfortunately, not all platforms support zero-conf deployment, and even those that do may have +limitations or trade-offs to consider. For example, some platforms may require specific file +structures, configuration files, or build processes that may not be compatible with +the way AI-developed apps are exported. + +In other words: while zero-conf deployment is an ideal goal, it may not always be achievable in practice, +and users may need to be prepared to make some manual adjustments or configurations in certain cases. + +## Tips and tricks to work towards zero-conf deployment {#tips-and-tricks-zero-conf-deployment} + +:::tip +A good practice to check exported code for zero-conf compatibility is to try deploying it locally +using a tool like Docker or a local development server before attempting to deploy it to a cloud platform. +This can help identify any issues or missing components that may need to be addressed before deployment. +::: + +During development, we can follow certain practices to improve the chances of achieving zero-conf deployment. + +Keep the stack small: the more dependencies and services your app relies on, the more complex the deployment process becomes. + +Use standard tools and configurations: sticking to widely used tools and configurations can increase compatibility +with various deployment platforms. + +Document your app's requirements and dependencies clearly: this can help others understand what is needed to +deploy the app successfully and can also assist in troubleshooting any issues that arise during deployment. + +Audit security and privacy best practices: ensuring that your app follows security and privacy best practices +can help prevent issues during deployment and operation. Avoid hardcoding secrets, use environment variables, +and regularly review your dependencies for vulnerabilities. + +Deployment checklist: +- [ ] App runs locally without errors +- [ ] All secrets/keys are out of your code! +- [ ] README explains setup & usage +- [ ] Build/export scripts work +- [ ] Tested app in a browser/incognito window +- [ ] Backups: Save a copy of your project! +- [ ] Choose a reliable host that meets your needs +- [ ] Shared the link with a friend — get feedback +- [ ] Celebrate your first deploy! 🎉 + +## Zero-conf deployment at mittwald {#zero-conf-deployment-at-mittwald} + +mittwald offers a zero-conf deployment option for AI-developed apps, +allowing users to deploy their apps directly from GitHub with minimal setup. + +Currently, there are two main paths for zero-conf deployment of AI-developed apps: +- Manually via mittwald CLI +- Automated via GitHub Actions + +The recommended approach is to start with the manual CLI deployment to understand the +process and then move towards automation with GitHub Actions for a more streamlined +and efficient deployment workflow. + +A separate extension for mStudio is also in the works, which will further simplify +the deployment process by providing an integrated experience within the development environment. + +## Quickstart guide for zero-conf deployment of AI-developed apps {#quickstart-zero-conf-deployment-ai-developed-apps} + +Prerequisites: +- An AI-developed app with a GitHub repository +- A mittwald hosting account +- Basic understanding of Git and GitHub +- mittwald CLI installed and configured + +Manual quickstart steps: +1. Prepare your AI-developed app for deployment: verify that it runs locally and that all dependencies are installed. + +```shellsession +user@local $ git clone https://github.com//.git +user@local $ cd +``` + +2. Make sure your local repository is in sync with GitHub and that your changes are committed and pushed. + +```shellsession +user@local $ git pull +user@local $ git status +``` + +3. In your app folder, use the mittwald CLI to create a project and run the deployment command. + +```shellsession +user@local $ mw project create --description= --update-context +user@local $ mw experimental deploy +``` + +Initial deployment takes a few minutes while the app is built and the hosting environment is set up. +Once the deployment is complete, you can access your app via the provided URL. + +Test your app in a browser, and if you encounter any issues, check the logs and configuration to troubleshoot. + +After successful deployment, you can set up a GitHub Action to automate future deployments whenever you push +changes to your repository. Leverage git tags to manage releases and rollbacks effectively. + +Related guides for deeper setup: + +- For container-based CI/CD with GitHub Actions, see [Deploying containerized applications with GitHub Actions](/docs/v2/guides/deployment/container-actions/). +- For advanced deployment workflows and CI examples, see [Application deployment with deployer](/docs/v2/guides/deployment/deployer/). +- For container concepts, stack files, and registry setup, see [Containers](/docs/v2/platform/workloads/containers/). +- For declarative stack deployment commands, see [mw stack command reference](/docs/v2/cli/reference/stack/). + +## Moving forward: Best practices for success {#moving-forward-best-practices} + +As you prepare to deploy, consider these practices that help apps succeed: + +- **Security and privacy matter.** Remove hardcoded secrets, use environment variables, and keep dependencies +up to date. These practices are straightforward and make your app more reliable. +- **Test early.** Deploy locally first, share with friends, and gather feedback before going live. +- **Community is here.** Our mittwald Discord server is a great place to ask questions, share what you're building, +and learn from other developers. +- **One size doesn't fit all.** Zero-conf deployment works great for many AI-developed apps. If your app has specific needs — complex +databases, custom infrastructure, or compliance requirements — that's fine too. Plan accordingly and don't hesitate to +reach out for guidance. + +You've built something cool. Ship it, learn from it, and iterate. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/guides/deployment/ai_developed_apps.mdx b/i18n/de/docusaurus-plugin-content-docs/current/guides/deployment/ai_developed_apps.mdx new file mode 100644 index 000000000..55cd1b9da --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/guides/deployment/ai_developed_apps.mdx @@ -0,0 +1,197 @@ +--- +title: Deployment von mit KI entwickelten Apps +sidebar_label: Mit KI entwickelte Apps +tags: + - Deployment + - GitHub + - Apps +description: Struktur und Schnellstart zum Deployen von mit KI entwickelten Apps mit einem Zero-Conf-Ansatz +--- + +## Einführung / Motivation {#introduction-motivation} + +Mit rasant voranschreitenden KI-getriebenen Entwicklungswerkzeugen ist die Erstellung von Anwendungen zugänglicher als je zuvor. +Wir möchten es so einfach wie möglich machen, die von dir erstellten Apps — ob schnell prototypisiert oder durchdacht entwickelt — selbstbewusst in die Welt zu bringen und dort zu teilen. + +Neben schnellem Prototyping und Entwicklung möchten wir es Nutzern ermöglichen, ihre +mit KI entwickelten Apps einfach mit anderen zu teilen und in Produktionsumgebungen bereitzustellen, ohne sich +mit komplexen Bereitstellungsprozessen oder Konfigurationen auseinandersetzen zu müssen. + +Ob du eine kleine geschäftliche App oder eine komplexere Anwendung mit KI-getriebener Entwicklung erstellst — dieser Guide hilft dir, +deine App von deinem lokalen Rechner (oder einer Cloud-basierten IDE) mit minimalem Aufwand in die Welt zu bringen. + +Eine App bereitzustellen ist spannend — und es lohnt sich, das durchdacht zu tun. Compliance, Datenschutz, Sicherheit und operative +Verantwortung sind wichtig. Wir empfehlen dir, dich an unsere Community zu wenden, wenn du Fragen hast. + +## Überblick über die mit KI entwickelte App-Landschaft {#ai-developed-app-landscape-overview} + +Apps, die durch KI-getriebene Entwicklung entstehen, sind leicht zu erstellen, und es gibt eine Vielzahl von Bereitstellungsoptionen. + +Verschiedene Plattformen bieten unterschiedliche Vorteile und Nachteile. Anbieter wie Replit und Lovable priorisieren Entwicklungsgeschwindigkeit +und Benutzerfreundlichkeit mit ihren speziellen Projektvorlagen, Buildsystemen und Bereitstellungspipelines. Dieser Komfort +geht mit einem Nachteil einher: Eine spätere Migration auf eine andere Plattform kann Nacharbeit erfordern. +Andererseits erhältst du einen schnellen Weg in die Produktion mit integrierten Werkzeugen und Support. + +Plattformen wie GitHub und mittwald bieten dagegen flexiblere und standardisierte +Bereitstellungsoptionen, die leicht an verschiedene Umgebungen angepasst werden können. + +Durch die Verwendung von GitHub als zentrales Repository für deine mit KI entwickelte App kannst du +eine klare Historie von Änderungen bewahren, mit anderen zusammenarbeiten und in verschiedene Plattformen +bereitstellen, ohne an ein spezifisches Vendor-Ökosystem gebunden zu sein. + +Dieser Ansatz bietet dir größere Freiheit und Kontrolle über die Bereitstellung deiner App, +während du weiterhin von der Leichtigkeit und Geschwindigkeit der KI-getriebenen Entwicklung profitierst. + +## GitHub ist unser Anker {#github-is-our-anchor} + +Wenn wir nach GitHub exportieren können, haben wir gute Chancen, überall zu deployen. + +Die meisten Plattformen unterstützen GitHub als Quelle für die Bereitstellung. Ein gut strukturiertes +GitHub-Repository ermöglicht bessere Zusammenarbeit, Versionskontrolle und Integration +mit verschiedenen Bereitstellungstools und -diensten. Falls GitHub nicht die bevorzugte Git-Plattform ist, +gelten die gleichen Prinzipien für jeden anderen Git-Hosting-Dienst mit ähnlichen Funktionen. + +Mit dem Moment, in dem wir unsere mit KI entwickelte App nach GitHub exportieren können, erschließen sich +vielfältige Bereitstellungsoptionen, darunter Continuous Integration und Continuous Deployment (CI/CD) +Pipelines und Containerisierung. + +Viele Tools bieten bidirektionale Synchronisierung mit GitHub. Das bedeutet, dass Änderungen im +GitHub-Repository automatisch in der Bereitstellungsumgebung sichtbar werden und umgekehrt. +Dies ermöglicht einen nahtloseren Entwicklungs- und Bereitstellungsprozess, +denn Entwickler können an ihrem Code in GitHub arbeiten und profitieren gleichzeitig +von einer live-Bereitstellungsumgebung. + +## Prinzipien und Grenzen von Zero-Conf-Deployments {#principles-and-limits-of-zero-conf-deployments} + +:::warning +Die Exportqualität variiert, daher solltest du zuerst lokal testen. Ein gut strukturierter Export mit allem notwendigen Code, +Konfiguration und Build-Dateien macht Bereitstellung und Wartung viel einfacher. +Ein unvollständiger Export erfordert möglicherweise Nacharbeit bei der Bereitstellung oder Wartung und kann +Probleme mit Versionskontrolle und Zusammenarbeit verursachen. +::: + +Da die meisten Plattformen mit benutzerdefinierten Pipelines und Konfigurationen bereitstellen, +müssen wir einen gemeinsamen Nenner für Zero-Conf-Deployment definieren. +In diesem Kontext bedeutet Zero-Conf-Deployment, dass wir den exportierten Code von GitHub nehmen +und ihn auf einer Plattform bereitstellen können, ohne manuelle Änderungen oder Konfigurationen vornehmen zu müssen. + +Mit anderen Worten: Endnutzer sollten ihre mit KI entwickelte App mit minimalem Setup bereitstellen können, +idealerweise nur durch das Verbinden ihres GitHub-Repositorys mit einer Bereitstellungsplattform, die +Zero-Conf-Deployment unterstützt. + +Unglücklicherweise unterstützen nicht alle Plattformen Zero-Conf-Deployment, und selbst die, die es tun, können +Einschränkungen oder Kompromisse haben. Beispielsweise können einige Plattformen spezifische Dateistrukturen, +Konfigurationsdateien oder Build-Prozesse erfordern, die nicht damit kompatibel sind, +wie mit KI entwickelte Apps exportiert werden. + +Mit anderen Worten: Während Zero-Conf-Deployment ein ideales Ziel ist, ist es in der Praxis nicht immer erreichbar, +und Nutzer müssen möglicherweise manuelle Anpassungen oder Konfigurationen vornehmen. + +## Tipps und Tricks auf dem Weg zu Zero-Conf-Deployment {#tips-and-tricks-zero-conf-deployment} + +:::tip +Eine gute Praktik, um exportierten Code auf Zero-Conf-Kompatibilität zu überprüfen, ist es, ihn lokal +mit einem Tool wie Docker oder einem lokalen Entwicklungsserver bereitzustellen, bevor du ihn auf einer Cloud-Plattform bereitstellst. +Dies kann dabei helfen, Probleme oder fehlende Komponenten zu identifizieren, die vor der Bereitstellung behoben werden müssen. +::: + +Während der Entwicklung können wir bestimmte Praktiken befolgen, um die Chancen auf Zero-Conf-Deployment zu verbessern. + +Halte den Stack klein: Je mehr Abhängigkeiten und Services deine App benötigt, desto komplexer wird der Bereitstellungsprozess. + +Nutze Standard-Tools und -Konfigurationen: Das Befolgen von weit verbreiteten Tools und Konfigurationen kann die Kompatibilität +mit verschiedenen Bereitstellungsplattformen erhöhen. + +Dokumentiere die Anforderungen und Abhängigkeiten deiner App klar: Dies kann anderen helfen zu verstehen, was für eine +erfolgreiche Bereitstellung der App erforderlich ist, und kann auch bei der Fehlerbehebung helfen. + +Überprüfe bewährte Verfahren für Sicherheit und Datenschutz: Eine App, die Sicherheits- und Datenschutzrichtlinien befolgt, +kann Probleme bei der Bereitstellung und im laufenden Betrieb verhindern. Vermeide hartcodierte Secrets, verwende Umgebungsvariablen, +und überprüfe deine Abhängigkeiten regelmäßig auf Sicherheitslücken. + +Bereitstellungs-Checkliste: +- [ ] App läuft lokal ohne Fehler +- [ ] Alle Secrets/Keys sind nicht in deinem Code! +- [ ] README erklärt Setup & Verwendung +- [ ] Build-/Export-Skripte funktionieren +- [ ] App in einem Browser/Incognito-Fenster getestet +- [ ] Backups: Speichere eine Kopie deines Projekts! +- [ ] Wähle einen zuverlässigen Host, der deine Anforderungen erfüllt +- [ ] Teile den Link mit einem Freund — hole Feedback ein +- [ ] Feiere dein erstes Deployment! 🎉 + +## Zero-Conf-Deployment bei mittwald {#zero-conf-deployment-at-mittwald} + +mittwald bietet eine Zero-Conf-Deployment-Option für mit KI entwickelte Apps, +die es Nutzern ermöglicht, ihre Apps direkt von GitHub mit minimalem Setup bereitzustellen. + +Gegenwärtig gibt es zwei Hauptwege für das Zero-Conf-Deployment von mit KI entwickelten Apps: +- Manuell über die mittwald-CLI +- Automatisiert über GitHub Actions + +Der empfohlene Ansatz ist, mit der manuellen CLI-Bereitstellung zu beginnen, um den +Prozess zu verstehen, und dann zur Automatisierung mit GitHub Actions für einen strafferen +und effizienter Bereitstellungs-Workflow überzugehen. + +Eine separate Erweiterung für mStudio ist in Entwicklung, die den +Bereitstellungsprozess durch eine integrierte Erfahrung in der Entwicklungsumgebung weiter vereinfacht. + +## Schnellstart-Anleitung zum Zero-Conf-Deployment von mit KI entwickelten Apps {#quickstart-zero-conf-deployment-ai-developed-apps} + +Voraussetzungen: +- Eine mit KI entwickelte App mit einem GitHub-Repository +- Ein mittwald-Hosting-Konto +- Grundlegendes Verständnis von Git und GitHub +- mittwald-CLI installiert und konfiguriert + +Manuell durchzuführende Schritte: +1. Bereite deine mit KI entwickelte App für die Bereitstellung vor: Vergewissere dich, dass sie lokal läuft und dass alle Abhängigkeiten installiert sind. + +```shellsession +user@local $ git clone https://github.com//.git +user@local $ cd +``` + +2. Stelle sicher, dass dein lokales Repository mit GitHub synchron ist und dass deine Änderungen committed und gepusht sind. + +```shellsession +user@local $ git pull +user@local $ git status +``` + +3. Verwende in deinem App-Ordner die mittwald-CLI, um ein Projekt zu erstellen und das Bereitstellungskommando auszuführen. + +```shellsession +user@local $ mw project create --description= --update-context +user@local $ mw experimental deploy +``` + +Die erste Bereitstellung dauert einige Minuten, während die App gebaut und die Hosting-Umgebung eingerichtet wird. +Sobald die Bereitstellung abgeschlossen ist, kannst du deine App über die bereitgestellte URL aufrufen. + +Teste deine App in einem Browser, und falls du Probleme hast, überprüfe die Logs und Konfiguration zur Fehlerbehebung. + +Nach erfolgreicher Bereitstellung kannst du eine GitHub Action einrichten, um zukünftige Bereitstellungen zu automatisieren, wenn du +Änderungen in dein Repository pushst. Nutze Git-Tags, um Releases und Rollbacks effektiv zu verwalten. + +Weiterführende Guides für tiefergehendes Setup: + +- Für containergestützte CI/CD mit GitHub Actions, siehe [Deployment von containerisierten Anwendungen mit GitHub Actions](/docs/v2/guides/deployment/container-actions/). +- Für erweiterte Bereitstellungs-Workflows und CI-Beispiele, siehe [Application Deployment mit deployer](/docs/v2/guides/deployment/deployer/). +- Für Container-Konzepte, Stack-Dateien und Registry-Setup, siehe [Container](/docs/v2/platform/workloads/containers/). +- Für deklarative Stack-Bereitstellungsbefehle, siehe [mw stack Befehlsreferenz](/docs/v2/cli/reference/stack/). + +## Auf zum Erfolg: Best Practices {#moving-forward-best-practices} + +Während du dich auf die Bereitstellung vorbereitest, berücksichtige diese Praktiken, die Apps zum Erfolg bringen: + +- **Sicherheit und Datenschutz sind wichtig.** Entferne hartcodierte Secrets, verwende Umgebungsvariablen und halte Abhängigkeiten aktuell. +Diese Praktiken sind unkompliziert und machen deine App zuverlässiger. +- **Teste früh.** Stelle lokal bereit, teile mit Freunden und hole dir Feedback ein, bevor du live gehst. +- **Community ist hier.** Unser mittwald Discord-Server ist ein großartiger Ort, um Fragen zu stellen, deine Projekte zu teilen, +und von anderen Entwicklern zu lernen. +- **Eine Größe passt nicht für alle.** Zero-Conf-Deployment funktioniert großartig für viele mit KI entwickelte Apps. Falls deine App spezifische Anforderungen hat — komplexe +Datenbanken, benutzerdefinierte Infrastruktur oder Compliance-Anforderungen — das ist kein Problem. Plane entsprechend und +zögere nicht, uns um Orientierung zu bitten. + +Du hast etwas Cooles gebaut. Starte es, lerne daraus und iteriere weiter.