Merge pull request #94 from mittwald/next

Umbrella PR: Content and index page restructuring

.github/workflows/docusaurus.yml

@@ -9,6 +9,9 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+  schedule:
+    - cron: '0 0 * * *'
+
 jobs:
   # Build job
   build:
@@ -19,7 +22,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: "18"
+          node-version: "20"
           cache: npm
       - name: Restore cache
         uses: actions/cache@v4
@@ -33,6 +36,8 @@ jobs:
             ${{ runner.os }}-docusaurus-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
       - name: Install dependencies
         run: npm ci
+      - name: Generate API reference
+        run: npm run generate
       - name: Build
         run: npm run build
       - name: Upload Artifact

.gitignore

@@ -18,3 +18,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Generated by the build process
+/sidebar.reference.json

CONTRIBUTING.md

@@ -22,6 +22,17 @@ You can use the following commands to build this project locally:
 - `npm run build` to build a production release (this may be necessary to work with multi-lingual content).
 - `npm run serve` to serve a production release locally.
 
+## How-Tos
+
+### Updating translation files
+
+Translation of components is done using [Docuraurus' built-in translation file handling][docu-i18n]. To update the translation files, you can use the following steps:
+
+```
+$ npm run docusaurus write-translations
+$ npm run docusaurus write-translations -- -l de
+```
+
 [md]: https://www.markdownguide.org
 [mdx]: https://mdxjs.com
 [docu-md]: https://docusaurus.io/docs/markdown-features

Dockerfile

@@ -0,0 +1,3 @@
+FROM httpd:2.4-alpine
+
+RUN echo -e "<Directory /usr/local/apache2/htdocs>\n  AllowOverride All\n</Directory>" >> /usr/local/apache2/conf/httpd.conf

docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3"
+services:
+  web:
+    build: .
+    volumes:
+      - ./build:/usr/local/apache2/htdocs/
+    ports:
+      - "3000:80"

docs/api/howtos/create-nodejs.mdx

@@ -1,25 +1,31 @@
 ---
-sidebar_label: Installing a Node.js application
-title: Installing a Node.js application using the API
-description: Learn how to install a Node.js application via the mStudio API
+sidebar_label: Installing a Node.js or Python application
+title: Installing a Node.js or Python application using the API
+description: Learn how to install an application that starts its own webserver (like Node.js or Python) via the mStudio API
 tags:
   - Node.js
+  - Python
 ---
 
 import OperationHint from "@site/src/components/OperationHint";
 
 ## Prerequisites
 
-To install a Node.js application, you will need to have the following:
+To install a Node.js or Python application, you will need to have the following:
 
 - The project ID of an existing project ([how to create a project](../create-project))
-- The application and version ID of the generic custom Node.js application (see next section)
+- The application and version ID of the generic custom Node.js/Python application (see next section)
 
 ## Determine the app and app version ID
 
-Before installing a Node.js application, you will need to determine the application ID and version ID of the generic custom Node.js application.
+Before installing a Node.js or Python application, you will need to determine the application ID and version ID of the generic custom Node.js (or Python, respectively) application.
 
-For this, call the `/v2/apps` endpoint, and find the "Node.js" application. It should have a stable ID of `3e7f920b-a711-4d2f-9871-661e1b41a2f0`. You can then use that ID to retrieve the recommended version to install for this app, by calling the `/v2/apps/{appID}/versions` endpoint. You can filter the returned versions by the `recommended` property.
+For this, call the `/v2/apps` endpoint, and find the "Node.js" or "Python" application. These should have the following stable IDs:
+
+- Node.js: `3e7f920b-a711-4d2f-9871-661e1b41a2f0`
+- Python: `be57d166-dae9-4480-bae2-da3f3c6f0a2e`
+
+Use the respective ID, depending on whether you want to install a Node.js or Python application. You can then use that ID to retrieve the recommended version to install for this app, by calling the `/v2/apps/{appID}/versions` endpoint. You can filter the returned versions by the `recommended` property.
 
 Please note that the actual version is rather inconsequential, as it refers only to the starter template used to create the application. The actual version of the application will be determined by your own code.
 

docs/api/howtos/create-redis.mdx

@@ -8,6 +8,7 @@ tags:
 ---
 
 import OperationHint from "@site/src/components/OperationHint";
+import OperationLink from "@site/src/components/OperationLink";
 
 This article describes how to create a Redis database via the API.
 
@@ -17,7 +18,7 @@ To create a Redis database, you will need to have access to a project. Refer to
 
 ## List available Redis versions
 
-Set a `GET` request to the `/v2/redis-versions` endpoint to get a list of available Redis versions. ([endpoint documentation for `database-list-redis-versions`](https://developer.mittwald.de/reference/v2#tag/Database/operation/database-list-redis-versions))
+Set a `GET` request to the `/v2/redis-versions` endpoint to get a list of available Redis versions. (<OperationLink tag="database" operation="database-list-redis-versions">endpoint documentation for `database-list-redis-versions`</OperationLink>)
 
 ## Creating a Redis database
 

docs/api/howtos/manage-mailbox.mdx

@@ -7,8 +7,8 @@ tags:
   - Email
 ---
 
-import ApiSchema from "@theme/ApiSchema";
 import OperationHint from "@site/src/components/OperationHint";
+import SchemaFromSpec from "@site/src/components/openapi/SchemaFromSpec";
 
 ## Types of mailboxes
 
@@ -25,10 +25,10 @@ To manage email accounts, you will need an existing project. You can create a ne
 
 To create a new email account, send a `POST` request to the `/v2/projects/{projectID}/mailaddresses` endpoint. The request body must contain a JSON object with the following properties:
 
-<ApiSchema
-  example
-  id="v2"
-  pointer="#/components/schemas/de.mittwald.v1.mail.CreateMailAddress"
+<SchemaFromSpec
+  apiVersion="v2"
+  path="#/components/schemas/de.mittwald.v1.mail.CreateMailAddress"
+  withExample
 />
 
 :::caution
@@ -37,16 +37,16 @@ Take note of the password you set for the email account. You will not be able to
 
 :::
 
-<OperationHint tag="Mail" operation="mail-mailaddress-create" />
+<OperationHint tag="Mail" operation="mail-create-mail-address" />
 
 ## Create a new forwarding address
 
 A forwarding address is an email address that forwards all incoming emails to one or more other email addresses. To create a new forwarding address, send a `POST` request to the `/v2/projects/{projectID}/mailaddresses` endpoint. The request body must contain a JSON object with the following properties:
 
-<ApiSchema
-  example
-  id="v2"
-  pointer="#/components/schemas/de.mittwald.v1.mail.CreateForwardAddress"
+<SchemaFromSpec
+  apiVersion="v2"
+  path="#/components/schemas/de.mittwald.v1.mail.CreateForwardAddress"
+  withExample
 />
 
 ## Create a new delivery box
@@ -62,7 +62,7 @@ Take note of the password you set for the delivery box. You will not be able to
 
 :::
 
-<OperationHint tag="Mail" operation="mail-deliverybox-create" />
+<OperationHint tag="Mail" operation="mail-create-deliverybox" />
 
 ## Deleting email accounts
 

docs/api/intro.md

@@ -14,7 +14,7 @@ The mStudio v2 API uses `https://api.mittwald.de/v2/` as base URL for all API en
 You can find the full API specification in the [OpenAPI 3.0 format](https://spec.openapis.org/oas/v3.0.0) here:
 
 1. [OpenAPI 3.0 specification](https://api.mittwald.de/openapi) (machine-readable)
-2. [Rendered HTML documentation](/reference/v2) (human-readable)
+2. [Rendered HTML documentation](../../reference) (human-readable)
 
 ## Authentication
 

docs/api/sdks/cli.md

@@ -86,43 +86,43 @@ A few commands (like `mw [app|project] download`, `mw [app|project] ssh` and som
 
 1. **If you already have an existing SSH private key**, you can import the public key to your mStudio account with the following command:
 
-    ```
-    $ mw user ssh-key import
-    ```
-   
+   ```
+   $ mw user ssh-key import
+   ```
+
 2. **To create and import a new SSH keypair**, you can use the following command:
 
-    ```
-    $ mw user ssh-key create
-    ```
-   
+   ```
+   $ mw user ssh-key create
+   ```
+
 Usually, the key pair should be used automatically by the CLI. To explicitly specify the key pair to use (for example, if you receive a `too many authentication failures` error), you have a few options:
 
 1. All commands that require an SSH connection respect your systems [SSH configuration](https://linux.die.net/man/5/ssh_config) (typically in `~/.ssh/config`). You can specify the key to use for a specific host like this:
 
-    ```txt title="~/.ssh/config"
-    Host *.project.host
-      IdentityFile ~/.ssh/mstudio-cli
-    ```
-   
+   ```txt title="~/.ssh/config"
+   Host *.project.host
+     IdentityFile ~/.ssh/mstudio-cli
+   ```
+
 2. Alternatively, all commands that require an SSH connection accept a `--ssh-identity-file` flag that you can use to specify the key to use:
 
-    ```
-    $ mw app download ... --ssh-identity-file="~/.ssh/mstudio-cli"
-    ```
-   
+   ```
+   $ mw app download ... --ssh-identity-file="~/.ssh/mstudio-cli"
+   ```
+
 3. Instead of the `--ssh-identity-file` flag, you can also set the `MITTWALD_SSH_IDENTITY_FILE` environment variable to specify the key to use:
 
-    ```
-    $ export MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio-cli
-    $ mw app download ...
-    ```
-   
-    You can also set the `MITTWALD_SSH_IDENTITY_FILE` environment variable in your shell profile (`~/.zshrc` or `~/.bashrc`) to make it available in every shell session:
+   ```
+   $ export MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio-cli
+   $ mw app download ...
+   ```
+
+   You can also set the `MITTWALD_SSH_IDENTITY_FILE` environment variable in your shell profile (`~/.zshrc` or `~/.bashrc`) to make it available in every shell session:
 
-    ```
-    $ echo 'export MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio-cli' >> ~/.zshrc
-    ```
+   ```
+   $ echo 'export MITTWALD_SSH_IDENTITY_FILE=~/.ssh/mstudio-cli' >> ~/.zshrc
+   ```
 
 ## General usage
 

docs/technologies/_category_.yml → docs/platform/_category_.yml

@@ -1,4 +1,4 @@
-label: Technologies
+label: Platform
 position: 1
 link:
   type: generated-index

docs/platform/databases/mysql.mdx

@@ -0,0 +1,116 @@
+---
+title: MySQL
+sidebar_position: 10
+description: |
+  MySQL is an open-source relational database management system (RDBMS). It is a popular choice for web applications and is often used in combination with PHP. This guide will help you get started with MySQL on your mittwald space.
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import OperationHint from "@site/src/components/OperationHint";
+
+## Creating a MySQL database
+
+<Tabs groupId="access-mode">
+  <TabItem value="gui" label="mStudio UI">
+    To create a MySQL database in the mStudio, follow these steps:
+
+    1. Navigate to the project that you want to create the database in.
+    2. Select the "Databases" menu item in the sidebar.
+    3. Click the "Create Database" button and select "MySQL".
+    4. Enter a description for the database, select the desired version and choose a password for the database user.
+
+    After the installation has completed, observe the host and port in the details under connection information. You
+    need both for the configuration of your system.
+
+  </TabItem>
+  <TabItem value="cli" label="CLI">
+    To create a MySQL database from the CLI, run the following commands:
+
+    ```bash
+    $ mw database mysql create --description "My MySQL database" --version 8.0
+    ```
+
+    This command will prompt you to enter a password for the database user. To skip the prompt, use the `--password` option (be careful, because this will store the password in your shell history), or set the `MYSQL_PWD` environment variable, first:
+
+    ```bash
+    $ read -s MYSQL_PWD
+    $ export MYSQL_PWD
+    $ mw database mysql create ...
+    ```
+
+    There are additional flags that you can provide to set additional options:
+
+    - `--character-set` and `--collation` to set the [character set and collation](https://dev.mysql.com/doc/refman/8.0/en/charset-mysql.html) for the database. These default to `utf8mb4` and `utf8mb4_unicode_ci`, respectively. Usually, there is little reason to change these, except when migrating from an existing database.
+    - `--user-access-level` allows you to restrict the permissions of the database user. The default is `full`, which grants all permissions. You can also choose `readonly`.
+    - `--user-external` allows you to create a user that can connect from outside the mittwald cloud platform. This is disabled by default.
+
+    After the installation has completed, use the `mw database mysql get` command to observe the connection information.
+
+  </TabItem>
+  <TabItem value="api" label="API">
+
+    <OperationHint tag="Database" operation="database-create-mysql-database" />
+
+  </TabItem>
+</Tabs>
+
+## Operational concerns
+
+### Managed backup and recovery
+
+The mittwald cloud platform automatically creates backups of your projects and their databases at regular intervals. You can inspect the available backups as any time using the mStudio UI or the [`mw` CLI][cli], using the `mw backup list` command. You can also create a backup manually using the `mw backup create` command:
+
+```shellsession title="Local shell session"
+$ mw backup create --wait --expires 30d
+```
+
+To recover the contents of a single MySQL database, you can follow the following steps:
+
+1. Download a backup to your local machine:
+
+   ```shellsession title="Local shell session"
+   $ mw backup download <backup-id> --format tar --output backup.tar.gz
+   ```
+
+2. After downloading the backup, you can extract the database contents from the downloaded archive:
+
+   ```shellsession title="Local shell session"
+   $ database_id=<database-id>
+   $ tar xfz backup.tar.gz dbdump-${database_id/_/-}
+   ```
+
+   :::note Note that in the archive files, the database ID is spelled differently. Whereas it usually follows the format `mysql_XXXXXX`, in the archive, it is spelled with dashes instead of underscores, like `mysql-XXXXXX`. :::
+
+3. Recover the backup using the `mw database mysql import` command. For this, you need to have an SSH key set up on your local machine, which is also linked to your mStudio user account.
+
+   ```shellsession title="Local shell session"
+   $ database_id=<database-id>
+   $ mw database mysql import ${database_id} --input dbdump-${database_id/_/-}/*.sql.gz --gzip
+   ```
+
+### Manual backup and recovery
+
+You can use the [`mw` CLI][cli] to manually create (and restore) backups of your MySQL database. As a prerequisite, you need to have an SSH key set up on your local machine, which is also linked to your mStudio user account.
+
+To create a backup, run the following command:
+
+```shellsession title="Local shell session"
+$ mw database mysql dump <database-id> --output dump.sql.gz --gzip
+```
+
+In this command, replace `<database-id>` with the ID of the MySQL database you want to back up. The `--gzip` flag compresses the backup file, which can save disk space and reduce transfer times.
+
+:::tip
+
+If you want to create the backup with a different user than the one you are currently logged in with, you can use the `--ssh-user` flag to specify a different user for the SSH connection. However, you still need to make sure that an SSH key is set up on your local machine for that user.
+
+:::
+
+To restore a backup, run the following command:
+
+```shellsession title="Local shell session"
+$ mw database mysql import <database-id> --input dump.sql.gz --gzip
+```
+
+[cli]: /docs/v2/api/sdks/cli