Add documentation for DDEV integration

docs/platform/development/_category_.yml

@@ -0,0 +1,4 @@
+label: Development support
+position: 25
+link:
+  type: generated-index

docs/platform/development/ddev.md

@@ -0,0 +1,141 @@
+---
+title: Running PHP apps locally with DDEV
+sidebar_label: DDEV
+tags:
+  - PHP
+  - Deployment
+description: DDEV is a local development environment for PHP applications. It provides an easy way to run PHP apps locally, facilitating development and testing.
+---
+
+## Prerequisites
+
+### Required tools
+
+Before getting started, make sure you have the necessary tools installed on your local machine:
+
+- [DDEV](https://ddev.readthedocs.io/en/stable/): DDEV is a local development environment that simplifies setting up and managing PHP applications on your computer.
+- [Docker](https://www.docker.com/): Docker is a platform for developing, shipping, and running applications inside containers.
+
+It's also recommended to have the [mittwald CLI][cli] installed, although it's optional for this setup.
+
+### Setting up SSH connectivity
+
+To use the `ddev pull` and `ddev push` commands, you need to set up SSH connectivity between your local machine and your mittwald app. To do this, follow the ["SSH authentication" section][cli-ssh] of the mittwald CLI documentation.
+
+Additionally, the DDEV integration with mittwald requires SSH connectivity to work correctly from within the DDEV web container. Typically, all your SSH keys are passed into the DDEV container using an SSH agent when you run `ddev auth ssh`. However, if you encounter issues like `too many authentication failures`, you may need to manually configure your SSH keys inside the DDEV container. Have a look at the ["common issues"](#common-issues) section for more information.
+
+## Setting up a DDEV environment for a mittwald project
+
+The following instructions guide you through setting up a DDEV environment for your mittwald app. You can choose between using the mittwald CLI or manually configuring your DDEV environment.
+
+These instructions work both for setting up a new DDEV environment, and also for connecting a mittwald app to an existing DDEV environment.
+
+It's also up to you if you want to initialize an empty project and pull code and database from an already installed app on the server, or if you want to setup a DDEV environment for an already existing codebase on your local machine.
+
+### Using the mittwald CLI
+
+If you already have the [mittwald CLI][cli] installed, you can set up a DDEV project for your mittwald app with a single command.
+
+To initiate the setup, run the following command in your terminal, replacing `<app-id>` with your application ID (usually formatted as `a-xxxxx`), and `<project-name>` with a suitable name for your project:
+
+```shell-session
+$ # Create and enter project directory; alternatively, this may also be an
+    existing project, for example cloned from a Git repository
+$ mkdir project-dir && cd project-dir
+
+$ # Initialize DDEV environment
+$ mw ddev init <app-id> --project-name <project-name>
+
+$ # Optional: Pull code and database from server
+$ ddev pull mittwald
+```
+
+This command automatically configures a DDEV environment to closely match the environment of your existing mittwald app, including PHP and MySQL versions and the document root. Additionally, it installs and configures the [mittwald DDEV addon][ddev-addon], which integrates seamlessly with DDEV.
+
+:::tip
+
+You can update your DDEV environment to match any changes in your mittwald app's configuration at any time by running `mw ddev init` again.
+
+:::
+
+### Manual Setup
+
+If you don't have the mittwald CLI installed or prefer a manual approach, you can still set up a DDEV environment for your PHP app. Here's how:
+
+```shell-session
+$ ddev config \
+    --project-type <type> \
+    --php-version <php-version> \
+    --database mysql:<mysql-version>
+$ ddev get mittwald/ddev
+```
+
+Replace `<type>`, `<php-version>`, and `<mysql-version>` with the appropriate values for your project. After running these commands, your DDEV environment will be configured, and the [mittwald DDEV addon][ddev-addon] will be installed.
+
+During this setup, you'll be prompted for a [mittwald API token][apitoken] and your mittwald app's application ID (typically formatted as `a-xxxxx`).
+
+## Features
+
+### Pulling and pushing your code and database
+
+DDEV simplifies the process of synchronizing code and databases between your local environment and your mittwald app.
+
+To pull the code and database from your mittwald app to your local DDEV environment, use:
+
+```shell-session
+$ ddev pull mittwald
+```
+
+Conversely, to push your local code and database changes to your mittwald app, run the following command:
+
+```shell-session
+$ ddev push mittwald
+```
+
+:::warning
+
+Be cautious when using `ddev push` as it overwrites your mittwald app's code and database with data from your local environment. This command is intended for development purposes and doesn't implement a production-ready deployment strategy.
+
+:::
+
+### Using the mittwald CLI
+
+The [mittwald DDEV addon][ddev-addon] enables you to run the [mittwald CLI][cli] directly within your DDEV web container. This integration allows you to execute various mittwald CLI commands seamlessly.
+
+To utilize the mittwald CLI inside your DDEV environment, use the following syntax:
+
+```shell-session
+$ ddev mw <command>
+```
+
+Replace `<command>` with any supported command from the mittwald CLI.
+
+## Common issues
+
+### SSH connections fail with `too many authentication failures`
+
+This error may occur when you have a lot of SSH key pairs configured on your local machine. In this case, the remote server may reject the connection after too many failed authentication attempts.
+
+To circumvent this issue, you can manually configure your SSH keys inside the DDEV web container. To do this, follow these steps:
+
+0. Find the SSH key pair that you want to use for the connection, and make sure that the public key is added to your mStudio user profile. For the following steps, we'll assume that the SSH key is named `mstudio` and the private key is stored in `~/.ssh/mstudio`.
+
+1. Add the required SSH key directly to the DDEV web container by symlinking it into `.ddev/homeadditions`:[^1]
+
+   ```shell-session
+   $ mkdir -p .ddev/homeadditions/.ssh
+   $ ln -s ~/.ssh/mstudio ~/.ddev/homeadditions/.ssh/mstudio
+   ```
+
+2. Set the `MITTWALD_SSH_IDENTITY_FILE` environment variable to point to the symlinked SSH key:
+
+   ```shell-session
+   $ ddev config --web-environment-add MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio
+   ```
+
+[cli]: /docs/v2/api/sdks/cli
+[cli-ssh]: /docs/v2/api/sdks/cli/#ssh
+[apitoken]: /docs/v2/api/intro
+[ddev-addon]: https://github.com/mittwald/ddev
+
+[^1]: DDEV `homeadditions` are a mechanism to extend your home directory within the web container. Have a look at the [manual](https://ddev.readthedocs.io/en/stable/users/extend/in-container-configuration/) for more information.

docusaurus.config.ts

@@ -6,7 +6,7 @@ import { themes } from "prism-react-renderer";
 import { Options, ThemeConfig } from "@docusaurus/preset-classic";
 import { Options as ClientRedirectOptions } from "@docusaurus/plugin-client-redirects";
 
-const lightCodeTheme = themes.github;
+const lightCodeTheme = themes.oneLight;
 const darkCodeTheme = themes.dracula;
 
 const config: Config = {

i18n/de/docusaurus-plugin-content-docs/current/platform/development/ddev.md

@@ -0,0 +1,141 @@
+---
+title: PHP-Anwendungen lokal mit DDEV ausführen
+sidebar_label: DDEV
+tags:
+  - PHP
+  - Deployment
+description: DDEV ist eine lokale Entwicklungsumgebung für PHP-Anwendungen. Es kann verwendet werden, um PHP-Anwendungen auf einfache Weise lokal für Test- und Entwicklungszwecke zu starten.
+---
+
+## Voraussetzungen
+
+### Benötigte Werkzeuge
+
+Bevor du loslegen kannst, stelle sicher, dass du die erforderlichen Tools auf deinem lokalen Rechner installiert hast:
+
+- [DDEV](https://ddev.readthedocs.io/en/stable/): DDEV ist eine lokale Entwicklungsumgebung, die das Einrichten und Verwalten von PHP-Anwendungen auf deinem Computer vereinfacht.
+- [Docker](https://www.docker.com/): Docker ist eine Plattform zum Entwickeln, Deployment und Ausführen von Anwendungen in Containern.
+
+Wir empfehlen außerdem, die [mittwald CLI][cli] für die Einrichtung zu verwenden -- obwohl es auch ohne geht.
+
+### SSH-Konnektivität herstellen
+
+Um die Befehle `ddev pull` und `ddev push` verwenden zu können, musst du eine SSH-Verbindung zwischen deinem lokalen Rechner und deiner mittwald-App ermöglichen. Folge dazu dem Abschnitt ["SSH-Authentifizierung"][cli-ssh] der mittwald CLI-Dokumentation.
+
+Weiterhin ist für die korrekte Funktion der DDEV-Integration mit mittwald eine SSH-Konnektivität von innerhalb des DDEV-Webcontainers erforderlich. Normalerweise werden alle deine SSH-Schlüssel in den DDEV-Container über einen SSH-Agenten übergeben, wenn du `ddev auth ssh` ausführst. Wenn du jedoch Probleme wie `too many authentication failures` hast, musst du möglicherweise deine SSH-Schlüssel manuell im DDEV-Container konfigurieren. Siehe den Abschnitt ["Häufige Probleme"](#häufige-probleme) für weitere Informationen.
+
+## Einrichten einer neuen DDEV-Umgebung für ein mittwald-Projekt
+
+Die folgenden Anweisungen führen dich durch die Einrichtung einer DDEV-Umgebung für deine mittwald-App. Du kannst zwischen der Verwendung der mittwald CLI oder der manuellen Konfiguration deiner DDEV-Umgebung wählen.
+
+Diese Anweisungen funktionieren sowohl für die Einrichtung einer neuen DDEV-Umgebung als auch für das Verbinden einer mittwald-App mit einer vorhandenen DDEV-Umgebung.
+
+Dir steht es auch frei, ob du ein leeres Projekt initialisieren und Code und Datenbank von einer bereits installierten App auf dem Server abrufen möchtest, oder ob du eine DDEV-Umgebung für eine bereits vorhandene Codebasis auf deinem lokalen Rechner einrichten möchtest.
+
+### Mit der mittwald CLI
+
+Wenn du die [mittwald CLI][cli] bereits installiert hast, kannst du mit einem einzigen Befehl ein DDEV-Projekt für deine mittwald-App einrichten.
+
+Um die Einrichtung zu starten, führe den folgenden Befehl in deinem Terminal aus und ersetze `<app-id>` durch deine App-ID (üblicherweise im Format `a-xxxxx`) und `<project-name>` durch einen geeigneten Namen für dein Projekt:
+
+```shell-session
+$ # Projektverzeichnis erstellen und betreten; alternativ kann dies auch ein
+    vorhandenes Projekt sein, z. B. geklont aus einem Git-Repository
+$ mkdir project-dir && cd project-dir
+
+$ # DDEV-Umgebung initialisieren
+$ mw ddev init <app-id> --project-name <project-name>
+
+$ # Optional: Code und Datenbank vom Server abrufen
+$ ddev pull mittwald
+```
+
+Dieser Befehl konfiguriert automatisch eine DDEV-Umgebung, die deiner vorhandenen mittwald-App weitgehend entspricht, einschließlich PHP- und MySQL-Versionen sowie des Document Roots. Darüber hinaus installiert und konfiguriert er das [mittwald DDEV-Addon][ddev-addon], das nahtlos mit DDEV integriert ist.
+
+:::tip
+
+Du kannst deine DDEV-Umgebung jederzeit aktualisieren, um etwaige Änderungen in der Konfiguration deiner mittwald-App zu berücksichtigen, indem du `mw ddev init` erneut ausführst.
+
+:::
+
+### Manuelle Einrichtung
+
+Wenn du das mittwald CLI nicht installiert hast oder eine manuelle Herangehensweise bevorzugst, kannst du dennoch eine DDEV-Umgebung für deine PHP-Anwendung einrichten. So geht's:
+
+```bash
+$ ddev config \
+    --project-type <type> \
+    --php-version <php-version> \
+    --database mysql:<mysql-version>
+$ ddev get mittwald/ddev
+```
+
+Ersetze `<type>`, `<php-version>` und `<mysql-version>` durch die entsprechenden Werte für dein Projekt. Nach Ausführung dieser Befehle wird deine DDEV-Umgebung konfiguriert, und das [mittwald DDEV-Addon][ddev-addon] wird installiert.
+
+Während dieser Einrichtung wirst du nach einem [mittwald API-Token][apitoken] und der App-ID deiner mittwald-App (üblicherweise im Format `a-xxxxx`) gefragt.
+
+## Funktionen
+
+### Code und Datenbank abrufen und übertragen
+
+DDEV vereinfacht den Prozess der Synchronisierung von Code und Datenbanken zwischen deiner lokalen Umgebung und deiner mittwald-App.
+
+Um den Code und die Datenbank von deiner mittwald-App in deine lokale DDEV-Umgebung zu laden, verwende den folgenden Befehl:
+
+```bash
+$ ddev pull mittwald
+```
+
+Umgekehrt, um lokale Code- und Datenbankänderungen auf deine mittwald-App hochzuladen, führe den folgenden Befehl aus:
+
+```bash
+$ ddev push mittwald
+```
+
+:::warning
+
+Sei vorsichtig bei der Verwendung von `ddev push`, da er deinen mittwald-App-Code und deine Datenbank mit Daten aus deiner lokalen Umgebung überschreibt. Dieser Befehl ist für Entwicklungszwecke gedacht und implementiert keine produktionsfähige Bereitstellungsstrategie.
+
+:::
+
+### Verwendung des mittwald CLI
+
+Das [mittwald DDEV-Addon][ddev-addon] ermöglicht es dir, das [mittwald CLI][cli] direkt in deinem DDEV-Webcontainer auszuführen. Diese Integration ermöglicht es dir, verschiedene mittwald CLI-Befehle nahtlos auszuführen.
+
+Um das mittwald CLI in deiner DDEV-Umgebung zu nutzen, verwende die folgende Syntax:
+
+```bash
+$ ddev mw <command>
+```
+
+Ersetze `<command>` durch einen unterstützten Befehl des mittwald CLI.
+
+## Häufige Probleme
+
+### SSH-Verbindungen schlagen mit `too many authentication failures` fehl
+
+Dieser Fehler kann auftreten, wenn du viele SSH-Schlüsselpaare auf deinem lokalen Rechner konfiguriert hast und der Remote-Server die Verbindung nach zu vielen fehlgeschlagenen Authentifizierungsversuchen ablehnt.
+
+Um dieses Problem zu umgehen, kannst du deine SSH-Schlüssel manuell im DDEV-Webcontainer konfigurieren. Führe dazu folgende Schritte aus:
+
+0. Finde das SSH-Schlüsselpaar, das du für die Verbindung verwenden möchtest, und stelle sicher, dass der öffentliche Schlüssel zu deinem mStudio-Benutzerprofil hinzugefügt ist. Für die folgenden Schritte gehen wir davon aus, dass der SSH-Schlüssel `mstudio` heißt und der private Schlüssel in `~/.ssh/mstudio` gespeichert ist.
+
+1. Füge den erforderlichen SSH-Schlüssel direkt zum DDEV-Webcontainer hinzu, indem du ihn in `.ddev/homeadditions` verlinkst:
+
+   ```shell-session
+   $ mkdir -p .ddev/homeadditions/.ssh
+   $ ln -s ~/.ssh/mstudio ~/.ddev/homeadditions/.ssh/mstudio
+   ```
+
+2. Setze die Umgebungsvariable `MITTWALD_SSH_IDENTITY_FILE` so, dass sie auf den verlinkten SSH-Schlüssel zeigt:
+
+   ```shell-session
+   $ ddev config --web-environment-add MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio
+   ```
+
+[cli]: /docs/v2/api/sdks/cli
+[cli-ssh]: /docs/v2/api/sdks/cli/#ssh
+[apitoken]: /docs/v2/api/intro
+[ddev-addon]: https://github.com/mittwald/ddev
+
+[^1]: DDEV-`homeadditions` sind ein Mechanismus, um dein Home-Verzeichnis innerhalb des Webcontainers zu erweitern. Siehe das [Handbuch](https://ddev.readthedocs.io/en/stable/users/extend/in-container-configuration/) für weitere Informationen.

src/components/HomepageFeatures/PlatformFeature.tsx

@@ -120,7 +120,7 @@ function PlatformTools() {
             }
             links={[
               <Link to="/docs/v2/api/sdks/cli">CLI</Link>,
-              <Link href="https://github.com/mittwald/ddev">
+              <Link to="/docs/v2/platform/development/ddev">
                 DDEV <NewBadge />
               </Link>,
             ]}

src/css/custom.css

@@ -212,6 +212,14 @@ nav a {
   font-size: 14px;
 }
 
+section.footnotes {
+  font-size: 0.8em;
+}
+
+.markdown {
+  font-size: 16px;
+}
+
 p {
   font-size: 16px;
 }