commit c09f064629107484204e3718ea1ae2efc9c4f228 Author: Thomas Soring Date: Thu Mar 5 21:05:12 2026 +0100 feat: Astro Starlight Docs-Site für BTC MAIN AI Application Layer Vollständige Dokumentations-Site mit: - Einstieg: Einführung, Schnellstart, Kernkonzepte - Guides: Deployment, CI/CD, Env-Vars, Domains, Logs - API-Referenz: Überblick, Auth, Applications, Deployments - Referenz: Tech Stack, FAQ - Dockerfile + nginx für containerisiertes Deployment Co-Authored-By: Claude Sonnet 4.6 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..eb7393a --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +dist/ +node_modules/ +.astro/ +.env +.env.* +*.local diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..42b7b20 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM node:20-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +RUN npm run build + +FROM nginx:alpine +COPY --from=builder /app/dist /usr/share/nginx/html +COPY nginx.conf /etc/nginx/conf.d/default.conf +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] diff --git a/astro.config.mjs b/astro.config.mjs new file mode 100644 index 0000000..8ae1103 --- /dev/null +++ b/astro.config.mjs @@ -0,0 +1,66 @@ +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'BTC MAIN · Managed AI Now', + description: 'Dokumentation des AI Application Layer — Deployment, Betrieb und API-Referenz', + defaultLocale: 'de', + logo: { + src: './src/assets/logo.svg', + replacesTitle: false, + }, + social: [ + { icon: 'external', label: 'BTC AG', href: 'https://www.btc-ag.com' }, + ], + editLink: { + baseUrl: 'https://git.coolai.btc-ag.cloud/thsoring/docs/edit/main/', + }, + sidebar: [ + { + label: 'Einstieg', + items: [ + { label: 'Einführung', slug: 'einstieg/einfuehrung' }, + { label: 'Schnellstart', slug: 'einstieg/schnellstart' }, + { label: 'Kernkonzepte', slug: 'einstieg/konzepte' }, + ], + }, + { + label: 'Anleitungen', + items: [ + { label: 'App deployen', slug: 'guides/app-deployen' }, + { label: 'CI/CD Pipelines', slug: 'guides/cicd-pipelines' }, + { label: 'Umgebungsvariablen', slug: 'guides/umgebungsvariablen' }, + { label: 'Custom Domains', slug: 'guides/custom-domains' }, + { label: 'Logs & Monitoring', slug: 'guides/logs-monitoring' }, + ], + }, + { + label: 'API-Referenz', + items: [ + { label: 'Überblick', slug: 'api/uebersicht' }, + { label: 'Authentifizierung', slug: 'api/authentifizierung' }, + { label: 'Applications', slug: 'api/applications' }, + { label: 'Deployments', slug: 'api/deployments' }, + ], + }, + { + label: 'Referenz', + items: [ + { label: 'Tech Stack', slug: 'referenz/tech-stack' }, + { label: 'FAQ', slug: 'referenz/faq' }, + ], + }, + ], + customCss: ['./src/styles/custom.css'], + head: [ + { + tag: 'meta', + attrs: { property: 'og:image', content: '/og-image.png' }, + }, + ], + components: {}, + }), + ], +}); diff --git a/nginx.conf b/nginx.conf new file mode 100644 index 0000000..cb9d862 --- /dev/null +++ b/nginx.conf @@ -0,0 +1,32 @@ +server { + listen 80; + root /usr/share/nginx/html; + index index.html; + + location / { + try_files $uri $uri/ $uri.html $uri/index.html =404; + } + + location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)$ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + location ~* \.html$ { + add_header Cache-Control "no-cache, must-revalidate"; + } + + gzip on; + gzip_vary on; + gzip_types + text/plain + text/css + text/javascript + application/javascript + application/json + image/svg+xml; + + add_header X-Frame-Options "SAMEORIGIN"; + add_header X-Content-Type-Options "nosniff"; + add_header Referrer-Policy "strict-origin-when-cross-origin"; +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..1b5768f --- /dev/null +++ b/package.json @@ -0,0 +1,17 @@ +{ + "name": "btc-main-ai-docs", + "type": "module", + "version": "1.0.0", + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/starlight": "^0.32.0", + "astro": "^5.0.0", + "sharp": "^0.33.0" + } +} diff --git a/src/assets/logo.svg b/src/assets/logo.svg new file mode 100644 index 0000000..71c8711 --- /dev/null +++ b/src/assets/logo.svg @@ -0,0 +1,7 @@ + + + + AI + + BTC MAIN + diff --git a/src/content/config.ts b/src/content/config.ts new file mode 100644 index 0000000..31b7476 --- /dev/null +++ b/src/content/config.ts @@ -0,0 +1,6 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), +}; diff --git a/src/content/docs/api/applications.mdx b/src/content/docs/api/applications.mdx new file mode 100644 index 0000000..0d0c2b3 --- /dev/null +++ b/src/content/docs/api/applications.mdx @@ -0,0 +1,210 @@ +--- +title: Applications API +description: REST-API-Referenz für Anwendungen — anlegen, lesen, aktualisieren und löschen. +sidebar: + order: 3 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Über die Applications-API lassen sich Anwendungen auf der Plattform vollständig programmatisch verwalten. + +**Base URL:** `https://coolai.btc-ag.cloud/api/v1` + +--- + +## Alle Anwendungen abrufen + +```http +GET /applications +``` + +Gibt alle Anwendungen zurück, auf die der Token Zugriff hat. + + + + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/applications \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + + + + +```json +[ + { + "id": 1, + "uuid": "abc123...", + "name": "meine-app", + "status": "running", + "fqdn": "https://meine-app.btc-ag.cloud", + "git_repository": "https://git.coolai.btc-ag.cloud/meinteam/meine-app", + "git_branch": "main", + "build_pack": "dockerfile" + } +] +``` + + + + +--- + +## Einzelne Anwendung abrufen + +```http +GET /applications/{uuid} +``` + + + + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + + + + +```json +{ + "uuid": "abc123...", + "name": "meine-app", + "status": "running", + "fqdn": "https://meine-app.btc-ag.cloud", + "git_repository": "https://git.coolai.btc-ag.cloud/meinteam/meine-app", + "git_branch": "main", + "build_pack": "dockerfile", + "ports_exposes": "3000", + "environment_variables": [ + { "key": "LOG_LEVEL", "value": "info", "is_secret": false } + ] +} +``` + + + + +--- + +## Anwendung anlegen (privates Repository) + +```http +POST /applications/private-deploy-key +``` + +Für Repositories auf `git.coolai.btc-ag.cloud`. + +**Request-Body:** + +| Feld | Typ | Pflicht | Beschreibung | +|---|---|---|---| +| `project_uuid` | string | ja | UUID des Projekts | +| `server_uuid` | string | ja | UUID des Ziel-Servers | +| `environment_name` | string | ja | z. B. `production` | +| `private_key_uuid` | string | ja | UUID des Deploy-Keys | +| `git_repository` | string | ja | SSH-URL des Repositories | +| `git_branch` | string | ja | Branch (z. B. `main`) | +| `build_pack` | string | ja | `dockerfile` \| `nixpacks` \| `static` | +| `ports_exposes` | string | ja | Port(s) der Anwendung (z. B. `3000`) | +| `name` | string | nein | Anzeigename | +| `fqdn` | string | nein | Domain(s), kommagetrennt | + + + + +```bash +curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-key \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "project_uuid": "", + "server_uuid": "", + "environment_name": "production", + "private_key_uuid": "", + "git_repository": "git@git.coolai.btc-ag.cloud:meinteam/meine-app.git", + "git_branch": "main", + "build_pack": "dockerfile", + "ports_exposes": "3000", + "name": "meine-app", + "fqdn": "https://meine-app.btc-ag.cloud" + }' +``` + + + + +```json +{ + "uuid": "newly-created-uuid", + "message": "Application created." +} +``` + + + + +--- + +## Anwendung aktualisieren + +```http +PATCH /applications/{uuid} +``` + +Aktualisiert einzelne Felder einer Anwendung. Nur übergebene Felder werden geändert. + +**Häufige Update-Felder:** + +| Feld | Beschreibung | +|---|---| +| `name` | Anzeigename | +| `fqdn` | Domain(s) | +| `git_branch` | Branch wechseln | +| `environment_variables` | Variablen als Newline-getrennter String | +| `dockerfile_location` | Pfad zum Dockerfile | + + + + +```bash +curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"fqdn": "https://neue-domain.btc-ag.cloud"}' +``` + + + + +```bash +curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "environment_variables": "DATABASE_URL=postgresql://...\nLOG_LEVEL=info" + }' +``` + + + + +--- + +## Anwendung löschen + +```http +DELETE /applications/{uuid} +``` + +```bash +curl -s -X DELETE https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +:::caution +Das Löschen einer Anwendung stoppt den Container und entfernt alle zugehörigen Konfigurationen. Deployment-Historien bleiben erhalten. +::: diff --git a/src/content/docs/api/authentifizierung.md b/src/content/docs/api/authentifizierung.md new file mode 100644 index 0000000..fd86f08 --- /dev/null +++ b/src/content/docs/api/authentifizierung.md @@ -0,0 +1,121 @@ +--- +title: Authentifizierung +description: API-Token erstellen und in Anfragen verwenden — Bearer-Authentifizierung für den AI Application Layer. +sidebar: + order: 2 +--- + +Die API des AI Application Layer verwendet **Bearer-Token-Authentifizierung**. Jeder API-Aufruf muss einen gültigen Token im `Authorization`-Header enthalten. + +--- + +## API-Token erstellen + +1. In der Plattform-Oberfläche anmelden +2. Oben rechts: **Profil → API-Tokens** +3. **"Neuen Token erstellen"** +4. Einen sprechenden Namen vergeben (z. B. `ci-pipeline-meine-app`) +5. Token **sofort kopieren** — er wird danach nicht mehr im Klartext angezeigt + +:::caution +Behandelt API-Tokens wie Passwörter. Niemals in Git einchecken, nicht in Logs ausgeben, nicht per E-Mail teilen. +::: + +--- + +## Token verwenden + +Jeder API-Request benötigt den Header: + +``` +Authorization: Bearer +``` + +### Beispiel mit curl + +```bash +# Token als Umgebungsvariable (sicher) +export COOLIFY_TOKEN="" + +curl -s https://coolai.btc-ag.cloud/api/v1/applications \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +### Beispiel mit Python + +```python +import httpx +import os + +token = os.environ["COOLIFY_TOKEN"] +base_url = "https://coolai.btc-ag.cloud/api/v1" + +headers = {"Authorization": f"Bearer {token}"} + +response = httpx.get(f"{base_url}/applications", headers=headers) +response.raise_for_status() +print(response.json()) +``` + +### Beispiel mit JavaScript/TypeScript + +```typescript +const token = process.env.COOLIFY_TOKEN; +const baseUrl = "https://coolai.btc-ag.cloud/api/v1"; + +const response = await fetch(`${baseUrl}/applications`, { + headers: { + Authorization: `Bearer ${token}`, + "Content-Type": "application/json", + }, +}); + +const apps = await response.json(); +``` + +--- + +## Token in CI/CD-Systemen + +Hinterlegt den Token als **Secret** in eurem CI/CD-System: + +**Gitea Actions:** +```yaml +# In .gitea/workflows/deploy.yml +steps: + - name: Deploy + env: + COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }} + run: | + curl -s -X GET \ + "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=${{ secrets.APP_UUID }}" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +Repository → **Settings → Secrets → "Neues Secret"** → `COOLIFY_TOKEN` + +--- + +## Token rotieren + +Wenn ein Token kompromittiert wurde oder ein Teammitglied das Unternehmen verlässt: + +1. Alten Token in der Plattform-Oberfläche **löschen** (Profil → API-Tokens) +2. Neuen Token erstellen +3. Neuen Token in allen CI/CD-Systemen und Scripts aktualisieren + +--- + +## Fehler bei der Authentifizierung + +| HTTP-Status | Bedeutung | +|---|---| +| `401 Unauthorized` | Token fehlt oder ist ungültig | +| `403 Forbidden` | Token ist gültig, aber ohne Berechtigung für diese Ressource | + +```json +// Beispiel-Response bei 401 +{ + "message": "Unauthenticated." +} +``` diff --git a/src/content/docs/api/deployments.md b/src/content/docs/api/deployments.md new file mode 100644 index 0000000..26f7725 --- /dev/null +++ b/src/content/docs/api/deployments.md @@ -0,0 +1,172 @@ +--- +title: Deployments API +description: Deployments auslösen, Status abfragen, Historie einsehen und laufende Deployments abbrechen. +sidebar: + order: 4 +--- + +## Deployment auslösen + +```http +GET /deploy?uuid={app-uuid}&force={true|false} +POST /deploy +``` + +Startet ein neues Deployment für die angegebene Anwendung. + +| Parameter | Typ | Beschreibung | +|---|---|---| +| `uuid` | string | UUID der Anwendung | +| `force` | boolean | `true`: Cache ignorieren, vollständigen Rebuild erzwingen | + +```bash +# Standard-Deployment (mit Cache) +curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=&force=false" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" + +# Force-Rebuild (kein Cache) +curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=&force=true" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +**Response:** + +```json +{ + "message": "Deployment queued.", + "deployment_uuid": "deploy-abc123" +} +``` + +--- + +## Deployment-Historie einer Anwendung + +```http +GET /deployments/applications/{app-uuid} +``` + +Gibt alle Deployments einer Anwendung zurück, neueste zuerst. + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.[] | {uuid, status, created_at}' +``` + +**Response:** + +```json +[ + { + "uuid": "deploy-abc123", + "status": "finished", + "created_at": "2026-03-05T10:00:00Z", + "logs": "..." + }, + { + "uuid": "deploy-xyz789", + "status": "failed", + "created_at": "2026-03-04T15:30:00Z", + "logs": "..." + } +] +``` + +--- + +## Einzelnes Deployment abrufen + +```http +GET /deployments/{deployment-uuid} +``` + +Gibt Details und den vollständigen Log eines einzelnen Deployments zurück. + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/deployments/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +**Response:** + +```json +{ + "uuid": "deploy-abc123", + "status": "finished", + "created_at": "2026-03-05T10:00:00Z", + "finished_at": "2026-03-05T10:02:34Z", + "logs": "[INFO] Cloning repository...\n[INFO] Building image...\n[INFO] Done." +} +``` + +--- + +## Laufende Deployments abbrechen + +```http +POST /deployments/{deployment-uuid}/cancel +``` + +Bricht ein aktuell laufendes Deployment ab. Hat keinen Effekt auf bereits abgeschlossene Deployments. + +```bash +curl -s -X POST \ + https://coolai.btc-ag.cloud/api/v1/deployments//cancel \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +:::note +Nach einem Abbruch läuft die zuletzt erfolgreich deployete Version weiter. Es gibt keinen Service-Ausfall. +::: + +--- + +## Deployment-Status-Übersicht + +| Status | Beschreibung | +|---|---| +| `queued` | In der Warteschlange | +| `in_progress` | Build oder Deploy läuft gerade | +| `finished` | Erfolgreich abgeschlossen | +| `failed` | Fehlgeschlagen | +| `cancelled` | Manuell abgebrochen | + +--- + +## Polling-Pattern + +Für automatisierte Workflows, die auf den Abschluss eines Deployments warten müssen: + +```bash +APP_UUID="" +COOLIFY_TOKEN="" + +# Deployment starten und UUID merken +DEPLOY_UUID=$(curl -s \ + "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=$APP_UUID&force=false" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq -r '.deployment_uuid') + +echo "Deployment gestartet: $DEPLOY_UUID" + +# Status pollen +while true; do + STATUS=$(curl -s \ + "https://coolai.btc-ag.cloud/api/v1/deployments/$DEPLOY_UUID" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq -r '.status') + + echo "Status: $STATUS" + + if [[ "$STATUS" == "finished" ]]; then + echo "Deployment erfolgreich." + break + elif [[ "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; then + echo "Deployment fehlgeschlagen: $STATUS" + exit 1 + fi + + sleep 10 +done +``` diff --git a/src/content/docs/api/uebersicht.md b/src/content/docs/api/uebersicht.md new file mode 100644 index 0000000..e901b28 --- /dev/null +++ b/src/content/docs/api/uebersicht.md @@ -0,0 +1,102 @@ +--- +title: API-Überblick +description: Grundlegendes zur REST-API des AI Application Layer — Base URL, Formate, Fehler und Konventionen. +sidebar: + order: 1 +--- + +Der AI Application Layer stellt eine vollständige REST-API bereit. Damit lassen sich alle Funktionen der Plattform automatisieren: Anwendungen anlegen und deployen, Konfiguration aktualisieren, Logs abrufen und Deployments steuern. + +--- + +## Base URL + +``` +https://coolai.btc-ag.cloud/api/v1 +``` + +Alle Endpunkte sind relativ zu dieser Base URL. Alle Anfragen erfolgen über HTTPS. + +--- + +## Format + +- **Request-Body**: `application/json` +- **Response**: `application/json` +- **Zeichensatz**: UTF-8 + +--- + +## Authentifizierung + +Alle API-Aufrufe erfordern einen Bearer-Token im `Authorization`-Header: + +``` +Authorization: Bearer +``` + +Details zur Token-Erstellung: [Authentifizierung](/api/authentifizierung/) + +--- + +## HTTP-Methoden + +| Methode | Verwendung | +|---|---| +| `GET` | Ressource lesen | +| `POST` | Ressource anlegen oder Aktion auslösen | +| `PATCH` | Ressource teilweise aktualisieren | +| `DELETE` | Ressource löschen | + +--- + +## Status-Codes + +| Code | Bedeutung | +|---|---| +| `200 OK` | Erfolgreich | +| `201 Created` | Ressource erfolgreich angelegt | +| `400 Bad Request` | Ungültige Anfrage (fehlende/falsche Parameter) | +| `401 Unauthorized` | Kein oder ungültiger Token | +| `403 Forbidden` | Keine Berechtigung für diese Ressource | +| `404 Not Found` | Ressource nicht gefunden | +| `422 Unprocessable Entity` | Validierungsfehler | +| `500 Internal Server Error` | Interner Fehler | + +--- + +## Fehler-Response + +Fehler werden einheitlich im folgenden Format zurückgegeben: + +```json +{ + "message": "The application was not found.", + "errors": { + "uuid": ["The UUID does not exist."] + } +} +``` + +--- + +## Paginierung + +Endpunkte, die Listen zurückgeben, unterstützen derzeit keine Paginierung — alle Einträge werden auf einmal zurückgegeben. + +--- + +## Beispiel-Aufruf + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/applications \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.[].name' +``` + +--- + +## Vollständige API-Referenz (Swagger) + +Die interaktive Swagger-Dokumentation mit allen Endpunkten und Schemas ist über die Plattform-Oberfläche erreichbar. +Loggt euch ein und navigiert zu: **Einstellungen → API → API-Referenz öffnen** diff --git a/src/content/docs/einstieg/einfuehrung.md b/src/content/docs/einstieg/einfuehrung.md new file mode 100644 index 0000000..f656bc6 --- /dev/null +++ b/src/content/docs/einstieg/einfuehrung.md @@ -0,0 +1,112 @@ +--- +title: Einführung +description: Was ist BTC MAIN — Managed AI Now und der AI Application Layer? Architektur, Zielgruppen und Einsatzbereiche. +sidebar: + order: 1 +--- + +## Was ist BTC MAIN — Managed AI Now? + +**BTC MAIN — Managed AI Now** ist das Managed-Plattform-Angebot der BTC AG für die Bereitstellung und den Betrieb moderner Anwendungen. +Ziel ist es, Entwicklungsteams eine leistungsfähige Deployment-Plattform an die Hand zu geben, +die sich wie Vercel oder Firebase anfühlt — aber vollständig unter Kontrolle der BTC AG betrieben wird: +souverän, sicher und ohne Abhängigkeit von Public-Cloud-Anbietern. + +--- + +## Der AI Application Layer + +Der **AI Application Layer** ist die technische Kernkomponente von BTC MAIN. +Er stellt die Infrastruktur und die Werkzeuge bereit, mit denen Anwendungen + +- aus einem Git-Repository automatisch gebaut und deployt werden, +- über definierte Domains mit automatischem TLS-Zertifikat erreichbar sind, +- über CI/CD-Pipelines kontinuierlich aktualisiert werden können, +- und im laufenden Betrieb überwacht und verwaltet werden können. + +Die Plattform basiert auf etablierten Open-Source-Technologien und läuft auf STACKIT IaaS in der Region Frankfurt (EU01). + +--- + +## Für wen ist diese Plattform? + +| Zielgruppe | Typische Aufgaben | +|---|---| +| **Entwickler** | Apps deployen, Umgebungsvariablen setzen, Logs einsehen, Pipelines konfigurieren | +| **DevOps / Platform Engineers** | Neue Projekte anlegen, Domains verwalten, Ressourcen skalieren, API-Automatisierung | +| **Betrieb / IT** | Betriebsstatus überwachen, Deployments nachvollziehen, Zugang verwalten | + +--- + +## Was kann ich auf der Plattform betreiben? + +Der AI Application Layer eignet sich für: + +- **Web-Anwendungen** (Frontend, Fullstack, APIs) — jede Sprache und jedes Framework, sofern ein Dockerfile vorhanden ist oder ein unterstütztes Runtime-Profil greift +- **Hintergrunddienste** (Worker, Daemons, Scheduler) +- **Statische Websites** (Dokumentationen, Landing Pages) +- **Managed Services** (Datenbanken, Message Broker — perspektivisch) + +:::note +Der Fokus liegt aktuell auf containerisierten Anwendungen. Bringt eure App als Docker-Image mit, oder stellt ein `Dockerfile` im Repository bereit. +::: + +--- + +## Architektur-Überblick + +``` +Entwickler / CI-Pipeline + | + | Git Push → Webhook + v ++------------------------+ +| Git (Gitea) | Versionsverwaltung & Webhooks +| git.coolai.btc-ag.cloud | ++----------+-------------+ + | + | Deployment-Trigger + v ++------------------------+ +| AI Application Layer | Deployment-Orchestrierung, +| (Plattform-Steuerung) | Build-Pipeline, Routing-Config ++----------+-------------+ + | + | Container deployen + v ++------------------------+ +| App-Runtime | Docker-Container +| (Application Server) | Eurer Anwendung ++----------+-------------+ + | + | HTTPS-Traffic + v ++------------------------+ +| Reverse Proxy (TLS) | Automatisches SSL via +| + Let's Encrypt | Let's Encrypt, Routing ++------------------------+ + | + | Öffentlicher Zugriff + v + https://eure-app.btc-ag.cloud +``` + +--- + +## Zugang erhalten + +Der Zugang zur Plattform wird über die IT der BTC AG bereitgestellt. +Meldet euren Bedarf über den internen IT-Servicedesk und gebt dabei an: + +- Projektname und kurze Beschreibung +- Gewünschte Domain(s) +- Beteiligtes Team / Kostenstelleninfo + +Nach der Freigabe erhaltet ihr: +- Zugang zur Plattform-Oberfläche +- Einen persönlichen API-Token +- Ein Gitea-Repository (oder Anbindung an ein bestehendes) + +:::tip +Benötigt ihr sofortigen Zugang für ein Pilotprojekt? Meldet euch direkt beim Platform-Team der BTC AG. +::: diff --git a/src/content/docs/einstieg/konzepte.md b/src/content/docs/einstieg/konzepte.md new file mode 100644 index 0000000..747f24b --- /dev/null +++ b/src/content/docs/einstieg/konzepte.md @@ -0,0 +1,134 @@ +--- +title: Kernkonzepte +description: Die wichtigsten Begriffe und Konzepte des AI Application Layer — Projekte, Anwendungen, Deployments, Domains und mehr. +sidebar: + order: 3 +--- + +Dieser Abschnitt erklärt die zentralen Konzepte der Plattform. Ein solides Verständnis dieser Grundbegriffe hilft dabei, die Plattform effektiv zu nutzen und Missverständnisse zu vermeiden. + +--- + +## Projekte + +Ein **Projekt** ist die übergeordnete Organisationseinheit. Projekte fassen zusammengehörige Ressourcen (Anwendungen, Datenbanken, Services) zu einer logischen Einheit zusammen. + +``` +Projekt: "E-Commerce-Plattform" +├── Anwendung: "frontend" +├── Anwendung: "api-server" +└── Datenbank: "postgres-prod" +``` + +Typische Projektzuschnitte: +- Ein Projekt pro Produkt oder Team +- Ein Projekt pro Domäne (z. B. `crm`, `reporting`, `ai-services`) + +--- + +## Anwendungen + +Eine **Anwendung** repräsentiert einen containerisierten Prozess — also euren Service, eure Web-App oder euren Worker. + +Jede Anwendung hat: +- ein **Repository** (Git-URL + Branch) +- ein **Build-Profil** (Dockerfile, Nixpacks, Static, ...) +- eine oder mehrere **Domains** +- **Umgebungsvariablen** (Build-Zeit und/oder Laufzeit) +- eine **Deployment-Historie** + +--- + +## Deployments + +Ein **Deployment** ist ein einzelner Durchlauf des Build-und-Deploy-Prozesses. Jedes Deployment + +1. klont das Repository am konfigurierten Branch/Commit, +2. baut das Docker-Image, +3. startet einen neuen Container, +4. schaltet den Reverse Proxy auf den neuen Container um. + +Jedes Deployment bekommt eine eigene ID und einen Status: + +| Status | Bedeutung | +|---|---| +| `queued` | Wartet auf Ausführung | +| `in_progress` | Build/Deploy läuft gerade | +| `finished` | Erfolgreich abgeschlossen | +| `failed` | Fehlgeschlagen (Logs prüfen) | +| `cancelled` | Manuell abgebrochen | + +Die komplette Deployment-Historie bleibt erhalten und ist über die API abrufbar. + +--- + +## Build-Profile + +Das **Build-Profil** legt fest, wie die Plattform aus dem Repository ein lauffähiges Image erstellt. + +| Profil | Beschreibung | +|---|---| +| **Dockerfile** | Euer eigenes `Dockerfile` im Repository-Root (empfohlen) | +| **Nixpacks** | Automatische Erkennung der Sprache/des Frameworks, kein Dockerfile nötig | +| **Static** | Statische Dateien (HTML/CSS/JS), direkt via nginx ausgeliefert | + +:::tip +Für maximale Kontrolle und Reproduzierbarkeit empfehlen wir immer ein eigenes `Dockerfile`. +::: + +--- + +## Domains & TLS + +Jede Anwendung kann unter einer oder mehreren **Domains** erreichbar sein. + +- **Automatisches TLS**: Let's Encrypt-Zertifikate werden automatisch ausgestellt und erneuert. +- **Custom Domains**: Beliebige Subdomains innerhalb von `btc-ag.cloud` oder eigene Domains (nach DNS-Konfiguration). +- **Routing**: Der Reverse Proxy leitet eingehende Anfragen anhand des Hostnamens an den richtigen Container weiter. + +Die Domain-Konfiguration greift unmittelbar nach dem nächsten Deployment. + +--- + +## Umgebungsvariablen & Secrets + +**Umgebungsvariablen** ermöglichen die Konfiguration einer Anwendung ohne Code-Änderungen. + +Es gibt zwei Typen: + +| Typ | Verfügbarkeit | Typischer Einsatz | +|---|---|---| +| **Build-Zeit** | Nur während `docker build` | `NEXT_PUBLIC_API_URL`, Build-Flags | +| **Laufzeit** | Im laufenden Container | `DATABASE_URL`, API-Keys, Feature-Flags | + +**Secrets** sind besonders geschützte Werte: Sie werden verschlüsselt gespeichert und nicht im Klartext in der Oberfläche oder in Logs angezeigt. + +--- + +## Services & Datenbanken + +Neben Anwendungen können auf der Plattform auch **verwaltete Services** betrieben werden — z. B. PostgreSQL, Redis oder andere Middleware. + +:::note +Der Ausbau des verwalteten Service-Angebots ist in Planung. Welche Services aktuell verfügbar sind, erfragt ihr beim Platform-Team. +::: + +--- + +## Webhook-basiertes Deployment + +Der **Webhook** ist der Auslöser für automatische Deployments. Wird in Gitea ein Push auf den konfigurierten Branch ausgeführt, sendet Gitea einen HTTP-Request an die Plattform — die daraufhin ein neues Deployment startet. + +Mehr dazu: [CI/CD Pipelines einrichten](/guides/cicd-pipelines/) + +--- + +## Reverse Proxy & Routing + +Alle eingehenden HTTPS-Anfragen laufen durch einen zentralen **Reverse Proxy** (Traefik). Er ist verantwortlich für: + +- TLS-Terminierung +- Routing nach Hostname zur richtigen Anwendung +- Automatische Zertifikatserneuerung + +Ihr müsst den Reverse Proxy nicht konfigurieren — das übernimmt die Plattform anhand eurer Domain-Einstellungen automatisch. diff --git a/src/content/docs/einstieg/schnellstart.mdx b/src/content/docs/einstieg/schnellstart.mdx new file mode 100644 index 0000000..a7a8b7c --- /dev/null +++ b/src/content/docs/einstieg/schnellstart.mdx @@ -0,0 +1,113 @@ +--- +title: Schnellstart +description: In wenigen Schritten zur ersten deployten Anwendung auf dem AI Application Layer. +sidebar: + order: 2 +--- + +import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components'; + +Dieser Guide begleitet euch von der ersten Anmeldung bis zur laufenden Anwendung. +Ihr benötigt dafür etwa **15–20 Minuten**. + +## Voraussetzungen + +- Zugang zur Plattform (API-Token und Zugangsdaten vom IT-Servicedesk) +- Git installiert (lokal) +- Docker installiert (lokal, zum Testen des Builds) +- Eine Anwendung mit `Dockerfile` oder einem unterstützten Runtime-Profil + +--- + +## Schritt-für-Schritt + + + +1. **Anmelden** + + Öffnet die Plattform-Oberfläche und meldet euch mit euren Zugangsdaten an. + + Nach dem Login seht ihr das Dashboard mit einer Übersicht aller euch zugänglichen Projekte. + +2. **Projekt wählen oder anlegen** + + Wählt ein bestehendes Projekt aus oder legt ein neues an: + + - Klick auf **"Neues Projekt"** + - Name und optionale Beschreibung eingeben + - Bestätigen + + Projekte sind logische Gruppen für zusammengehörige Anwendungen (z. B. `backend`, `frontend`, `worker`). + +3. **Neue Anwendung anlegen** + + Innerhalb des Projekts: **"Neue Ressource" → "Anwendung" → "Öffentliches/Privates Repository"** + + + + Füllt die Felder aus: + + | Feld | Beispiel | + |---|---| + | Repository-URL | `https://git.coolai.btc-ag.cloud/meinteam/meine-app` | + | Branch | `main` | + | Build-Pack | `Dockerfile` | + | Port | `3000` (oder euer App-Port) | + +4. **Domain konfigurieren** + + Unter **"Domains"** tragt ihr die gewünschte Adresse ein, z. B.: + + ``` + meine-app.btc-ag.cloud + ``` + + Das TLS-Zertifikat wird automatisch ausgestellt — kein manueller Schritt nötig. + +5. **Umgebungsvariablen setzen** + + Unter **"Umgebungsvariablen"** könnt ihr alle nötigen Konfigurationswerte hinterlegen. + + ``` + DATABASE_URL=postgresql://... + APP_ENV=production + LOG_LEVEL=info + ``` + + + +6. **Erstes Deployment auslösen** + + Klick auf **"Deployen"** — die Plattform: + + - Klont das Repository + - Baut das Docker-Image + - Startet den Container + - Aktiviert das Routing über den Reverse Proxy + + Ihr könnt den Build-Log in Echtzeit verfolgen. + +7. **Anwendung prüfen** + + Nach erfolgreichem Deployment ist die App unter der konfigurierten Domain erreichbar. + + Im Dashboard seht ihr: + - Deployment-Status (grün = läuft) + - Letzten Deployment-Zeitstempel + - Link zur laufenden Instanz + + + +--- + +## Nächste Schritte + +Jetzt, wo eure erste App läuft, richtet ihr am besten den automatischen Deployment-Trigger ein: + +- [CI/CD Pipelines einrichten](/guides/cicd-pipelines/) — bei jedem Push automatisch deployen +- [Umgebungsvariablen verwalten](/guides/umgebungsvariablen/) — Build- vs. Laufzeit-Variablen +- [Custom Domain hinzufügen](/guides/custom-domains/) — eigene Subdomain einbinden diff --git a/src/content/docs/guides/app-deployen.mdx b/src/content/docs/guides/app-deployen.mdx new file mode 100644 index 0000000..3df0d69 --- /dev/null +++ b/src/content/docs/guides/app-deployen.mdx @@ -0,0 +1,173 @@ +--- +title: App deployen +description: Schritt-für-Schritt-Anleitung für das Deployment einer Anwendung auf dem AI Application Layer — via UI und API. +sidebar: + order: 1 +--- + +import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components'; + +Dieser Guide zeigt, wie ihr eine neue Anwendung auf der Plattform einrichtet und deployt — sowohl über die Benutzeroberfläche als auch über die API. + +--- + +## Voraussetzungen + +- Aktiver Plattform-Zugang (API-Token vorhanden) +- Anwendungs-Repository in Gitea (`git.coolai.btc-ag.cloud`) +- `Dockerfile` im Repository-Root (empfohlen) oder Nixpacks-kompatible Projektstruktur +- Gewünschte Domain (Subdomain unter `btc-ag.cloud` oder eigene Domain) + +--- + +## Dockerfile-Anforderungen + +Ein gutes `Dockerfile` für die Plattform folgt diesen Grundsätzen: + +```dockerfile +# Multi-Stage Build — klein und sicher +FROM node:20-alpine AS builder +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY . . +RUN npm run build + +FROM node:20-alpine +WORKDIR /app +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/node_modules ./node_modules + +# Expliziter Port +EXPOSE 3000 + +# Kein Root +USER node + +CMD ["node", "dist/server.js"] +``` + +**Wichtige Punkte:** +- Den **Port explizit** via `EXPOSE` deklarieren — die Plattform liest diesen Wert aus. +- **Multi-Stage Builds** verwenden, um das finale Image klein zu halten. +- Den Container **nicht als Root** ausführen. +- Keine Secrets ins Image einbacken — alles über Umgebungsvariablen. + +--- + +## Deployment via Oberfläche + + + +1. **Repository verbinden** + + Im Dashboard: **Projekt öffnen → "Neue Ressource" → "Anwendung"** + + Repository-Typ wählen: + - **Öffentliches Repository**: GitHub, GitLab, beliebige öffentliche URL + - **Privates Repository (Deploy-Key)**: Gitea auf `git.coolai.btc-ag.cloud` (empfohlen) + +2. **Repository-Details eintragen** + + | Feld | Beschreibung | + |---|---| + | Repository-URL | `https://git.coolai.btc-ag.cloud/meinteam/meine-app` | + | Branch | z. B. `main` oder `production` | + | Build-Pack | `Dockerfile` | + | Dockerfile-Pfad | Standard: `./Dockerfile` | + | Port | Euer App-Port (z. B. `3000`, `8080`) | + +3. **Domain konfigurieren** + + Unter dem Tab **"Domains"**: + ``` + meine-app.btc-ag.cloud + ``` + TLS wird automatisch eingerichtet. + +4. **Umgebungsvariablen setzen** + + Unter **"Umgebungsvariablen"** alle nötigen Werte hinterlegen. + Secrets (Passwörter, Tokens) als **geheimen Wert** markieren. + +5. **Deployment starten** + + Klick auf **"Deployen"** — Build-Log erscheint in Echtzeit. + + + +--- + +## Deployment via API + + + + +```bash +curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-key \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "project_uuid": "", + "server_uuid": "", + "environment_name": "production", + "private_key_uuid": "", + "git_repository": "git@git.coolai.btc-ag.cloud:meinteam/meine-app.git", + "git_branch": "main", + "build_pack": "dockerfile", + "ports_exposes": "3000", + "name": "meine-app", + "domains": "https://meine-app.btc-ag.cloud" + }' +``` + + + + +```bash +# Deployment triggern (UUID aus dem App-Anlegen-Response) +curl -s -X GET \ + "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=&force=false" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + + + + +```bash +# Deployment-Status abfragen +curl -s https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.status' +``` + + + + +--- + +## Deployment-Verlauf + +Jedes Deployment wird mit ID, Zeitstempel, Status und vollständigem Log gespeichert. + +```bash +# Alle Deployments einer Anwendung +curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.[] | {id: .id, status: .status, created_at: .created_at}' +``` + +--- + +## Troubleshooting + +| Problem | Mögliche Ursache | Lösung | +|---|---|---| +| Build schlägt fehl | Fehler im Dockerfile | Build-Log prüfen | +| Container startet nicht | Falscher Port / fehlende Env-Var | Logs prüfen, Umgebungsvariablen kontrollieren | +| Domain nicht erreichbar | DNS noch nicht propagiert / TLS ausstehend | 5–10 Minuten warten, dann erneut prüfen | +| `Permission denied` beim Build | Root-Rechte im Container fehlen | `USER`-Direktive im Dockerfile prüfen | + + diff --git a/src/content/docs/guides/cicd-pipelines.md b/src/content/docs/guides/cicd-pipelines.md new file mode 100644 index 0000000..689c9d2 --- /dev/null +++ b/src/content/docs/guides/cicd-pipelines.md @@ -0,0 +1,157 @@ +--- +title: CI/CD Pipelines +description: Automatische Deployments mit Gitea-Webhooks und Gitea Actions — von Git Push bis Livegang. +sidebar: + order: 2 +--- + +Der AI Application Layer unterstützt zwei Ansätze für automatische Deployments: + +| Ansatz | Geeignet für | Komplexität | +|---|---|---| +| **Gitea Webhook → direkt deployen** | Einfache Projekte, schnelles Setup | Niedrig | +| **Gitea Actions / Pipeline** | Komplexere Workflows (Tests, Builds, Multi-Stage) | Mittel | + +--- + +## Option 1: Direkt-Deployment via Webhook + +Der einfachste Weg: Gitea sendet bei jedem Push auf einen Branch automatisch einen Webhook an die Plattform, die daraufhin ein Deployment startet. + +### Webhook-URL ermitteln + +Jede Anwendung auf der Plattform hat eine dedizierte Webhook-URL. Ihr findet sie in der Anwendungsübersicht unter **"Webhooks"** oder über die API: + +```bash +curl -s https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '{webhook: .manual_webhook_secret_gitea}' +``` + +### Webhook in Gitea einrichten + +1. Repository in Gitea öffnen: `https://git.coolai.btc-ag.cloud` +2. **Settings → Webhooks → Webhook hinzufügen → Gitea** + +| Feld | Wert | +|---|---| +| Ziel-URL | `https://coolai.btc-ag.cloud/api/v1/deploy?uuid=&force=false` | +| HTTP-Methode | `POST` | +| Content Type | `application/json` | +| Authorization-Header | `Bearer ` | +| Trigger | `Push Events` | +| Branch-Filter | z. B. `main` | + +3. **"Webhook testen"** — bei Erfolg erscheint im Anwendungs-Dashboard ein neues Deployment. + +### Webhook via Gitea API einrichten + +```bash +GITEA_TOKEN="" +GITEA_URL="https://git.coolai.btc-ag.cloud" +REPO_OWNER="meinteam" +REPO_NAME="meine-app" +APP_UUID="" +COOLIFY_TOKEN="" + +curl -s -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/hooks" \ + -H "Authorization: token $GITEA_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{ + \"type\": \"gitea\", + \"config\": { + \"url\": \"https://coolai.btc-ag.cloud/api/v1/deploy?uuid=$APP_UUID&force=false\", + \"content_type\": \"json\", + \"authorization_header\": \"Bearer $COOLIFY_TOKEN\" + }, + \"events\": [\"push\"], + \"active\": true + }" +``` + +--- + +## Option 2: Gitea Actions Pipeline + +Für Projekte, die vor dem Deployment Tests, Linting oder komplexere Build-Schritte benötigen, empfiehlt sich eine Gitea Actions Pipeline. + +### Beispiel: Node.js App mit Tests + +Datei: `.gitea/workflows/deploy.yml` + +```yaml +name: Build, Test & Deploy + +on: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Node.js einrichten + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Abhängigkeiten installieren + run: npm ci + + - name: Tests ausführen + run: npm test + + deploy: + needs: test + runs-on: ubuntu-latest + steps: + - name: Deployment auslösen + run: | + curl -s -X POST \ + "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=${{ secrets.APP_UUID }}&force=false" \ + -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" +``` + +### Secrets in Gitea hinterlegen + +Repository → **Settings → Secrets → "Neues Secret"**: + +| Name | Wert | +|---|---| +| `COOLIFY_TOKEN` | Euer API-Token | +| `APP_UUID` | UUID der Anwendung auf der Plattform | + +:::caution +Tragt Tokens und UUIDs **niemals direkt in die YAML-Datei** ein. Verwendet immer Gitea Secrets. +::: + +--- + +## Branch-Strategie + +Eine bewährte Strategie für den Umgang mit mehreren Umgebungen: + +| Branch | Umgebung | Deployment | +|---|---|---| +| `main` | Produktion | Automatisch bei Push | +| `staging` | Staging | Automatisch bei Push | +| Feature-Branches | – | Kein automatisches Deployment | + +Richtet dafür je eine Anwendung (mit eigener Domain und eigenem Webhook) pro Umgebung ein. + +--- + +## Deployment-Status prüfen + +Nach einem Trigger könnt ihr den aktuellen Status abfragen: + +```bash +# Letztes Deployment einer Anwendung +curl -s "https://coolai.btc-ag.cloud/api/v1/deployments/applications/" \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq 'first | {status: .status, started: .created_at}' +``` diff --git a/src/content/docs/guides/custom-domains.md b/src/content/docs/guides/custom-domains.md new file mode 100644 index 0000000..b65dabf --- /dev/null +++ b/src/content/docs/guides/custom-domains.md @@ -0,0 +1,87 @@ +--- +title: Custom Domains +description: Eigene (Sub-)Domains für Anwendungen einrichten — DNS-Konfiguration und automatisches TLS. +sidebar: + order: 4 +--- + +Jede Anwendung kann unter einer oder mehreren Domains erreichbar sein. TLS-Zertifikate werden automatisch über Let's Encrypt ausgestellt. + +--- + +## Subdomains unter btc-ag.cloud + +Für Subdomains unter `*.btc-ag.cloud` ist **kein DNS-Aufwand auf eurer Seite** nötig — das Platform-Team richtet die nötigen DNS-Einträge ein. + +Teilt dem Platform-Team mit: +- Gewünschte Subdomain (z. B. `meine-app.btc-ag.cloud`) +- Zugehörige Anwendung auf der Plattform + +Sobald der DNS-Eintrag gesetzt ist, genügt es, die Domain in der Anwendungskonfiguration einzutragen. + +--- + +## Eigene externe Domain + +Wenn ihr eine eigene Domain (z. B. `app.meinunternehmen.de`) verwenden möchtet: + +### 1. CNAME-Eintrag anlegen + +Legt bei eurem DNS-Provider einen CNAME-Eintrag an, der auf den Plattform-Eintrittspunkt zeigt: + +``` +app.meinunternehmen.de. CNAME coolai.btc-ag.cloud. +``` + +:::note +Bei Apex-Domains (ohne Subdomain, also z. B. `meinunternehmen.de`) ist ein CNAME nicht möglich. +Verwendet stattdessen einen A-Record — die IP-Adresse erhaltet ihr vom Platform-Team. +::: + +### 2. Domain in der Plattform eintragen + +Anwendung öffnen → **"Domains" → "Domain hinzufügen"**: + +``` +https://app.meinunternehmen.de +``` + +:::tip +Immer `https://` voranstellen — die Plattform konfiguriert sonst kein automatisches TLS. +::: + +### 3. TLS-Zertifikat + +Das Zertifikat wird automatisch beim nächsten Deployment oder innerhalb weniger Minuten ausgestellt. +Voraussetzung: Der DNS-Eintrag muss aktiv und propagiert sein. + +--- + +## Via API + +```bash +# Domain zu einer Anwendung hinzufügen +curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "fqdn": "https://app.meinunternehmen.de" + }' +``` + +Für mehrere Domains kommagetrennt: + +```bash +-d '{"fqdn": "https://app.meinunternehmen.de,https://www.meinunternehmen.de"}' +``` + +--- + +## Troubleshooting + +| Problem | Ursache | Lösung | +|---|---|---| +| Domain nicht erreichbar | DNS noch nicht propagiert | `dig app.meinunternehmen.de` ausführen, auf Auflösung warten | +| TLS-Fehler im Browser | Zertifikat noch nicht ausgestellt | 5–10 Minuten warten, dann erneut testen | +| Zertifikat für falsche Domain | `fqdn`-Feld enthält Tippfehler | Domain in der Anwendung prüfen und korrigieren | +| HTTP statt HTTPS | `https://`-Prefix fehlt | Domain-Eintrag mit `https://` beginnen | diff --git a/src/content/docs/guides/logs-monitoring.md b/src/content/docs/guides/logs-monitoring.md new file mode 100644 index 0000000..8e583f8 --- /dev/null +++ b/src/content/docs/guides/logs-monitoring.md @@ -0,0 +1,134 @@ +--- +title: Logs & Monitoring +description: Anwendungs- und Deployment-Logs einsehen — via Oberfläche und API. +sidebar: + order: 5 +--- + +Der AI Application Layer stellt zwei Arten von Logs bereit: **Deployment-Logs** (Build- und Deploy-Prozess) und **Container-Logs** (Laufzeit-Ausgabe der Anwendung). + +--- + +## Deployment-Logs + +Deployment-Logs zeigen den kompletten Ablauf eines Build-und-Deploy-Vorgangs: + +- Repository klonen +- Docker-Image bauen +- Container starten +- Reverse Proxy konfigurieren + +### Via Oberfläche + +Anwendung → **"Deployments"** → Deployment auswählen → **"Log anzeigen"** + +Der Log wird in Echtzeit aktualisiert, solange das Deployment läuft. + +### Via API + +```bash +# Deployment-Historie einer Anwendung +curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.[] | {id, status, created_at}' + +# Log eines einzelnen Deployments +curl -s https://coolai.btc-ag.cloud/api/v1/deployments/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.logs' +``` + +--- + +## Container-Logs (Laufzeit) + +Container-Logs sind die Standardausgaben (stdout/stderr) eurer laufenden Anwendung — also alles, was ihr mit `console.log`, `logger.info` oder äquivalenten Methoden ausgebt. + +### Via Oberfläche + +Anwendung → **"Logs"** — zeigt die letzten Zeilen in Echtzeit. + +### Via API + +```bash +# Aktuelle Logs der laufenden Instanz +curl -s https://coolai.btc-ag.cloud/api/v1/applications//logs \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +--- + +## Logging-Best-Practices + +Damit Logs nützlich sind, sollte eure Anwendung: + +**Strukturiert loggen (JSON)** + +```javascript +// Empfohlen: JSON-Format für maschinelle Auswertbarkeit +console.log(JSON.stringify({ + level: 'info', + message: 'Request verarbeitet', + path: '/api/users', + duration_ms: 42, + timestamp: new Date().toISOString() +})); +``` + +**Log-Level verwenden** + +``` +DEBUG — Detaillierte Diagnoseinformationen (nur Entwicklung) +INFO — Normaler Betriebsablauf +WARN — Unerwartete, aber handhabbare Situationen +ERROR — Fehler, die Aufmerksamkeit erfordern +``` + +**Keine Secrets in Logs** + +```javascript +// Schlecht +console.log(`Verbinde mit DB: ${databaseUrl}`); + +// Gut +console.log('Datenbankverbindung wird aufgebaut'); +``` + +--- + +## Statusüberwachung + +Der aktuelle Status jeder Anwendung ist im Dashboard sichtbar: + +| Status | Bedeutung | +|---|---| +| `running` | Anwendung läuft und ist erreichbar | +| `stopped` | Manuell gestoppt | +| `restarting` | Neustart läuft | +| `exited` | Container beendet (Fehler prüfen) | + +### Via API + +```bash +# Status aller Ressourcen auf einem Server +curl -s https://coolai.btc-ag.cloud/api/v1/servers//resources \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + | jq '.[] | {name: .name, status: .status}' +``` + +--- + +## Deployment bei Fehler abbrechen + +Läuft ein Deployment und ihr merkt, dass etwas schiefläuft: + +```bash +# Laufendes Deployment abbrechen +curl -s -X POST \ + https://coolai.btc-ag.cloud/api/v1/deployments//cancel \ + -H "Authorization: Bearer $COOLIFY_TOKEN" +``` + +:::tip +Nach einem fehlgeschlagenen Deployment läuft die zuletzt erfolgreiche Version weiter — es gibt keinen Ausfall durch einen gescheiterten Deploy. +::: diff --git a/src/content/docs/guides/umgebungsvariablen.md b/src/content/docs/guides/umgebungsvariablen.md new file mode 100644 index 0000000..7c83041 --- /dev/null +++ b/src/content/docs/guides/umgebungsvariablen.md @@ -0,0 +1,111 @@ +--- +title: Umgebungsvariablen +description: Konfiguration von Build- und Laufzeit-Variablen sowie sicherer Umgang mit Secrets. +sidebar: + order: 3 +--- + +Umgebungsvariablen sind der empfohlene Weg, um Anwendungen zu konfigurieren — ohne Werte ins Repository einzuchecken. + +--- + +## Typen + +| Typ | Verfügbar | Beispiel | +|---|---|---| +| **Build-Zeit** | Während `docker build` | `NEXT_PUBLIC_API_URL`, `VITE_APP_NAME` | +| **Laufzeit** | Im laufenden Container | `DATABASE_URL`, `JWT_SECRET`, `LOG_LEVEL` | + +Die meisten Variablen sind Laufzeit-Variablen. Build-Zeit-Variablen braucht ihr nur, wenn euer Build-Prozess Werte direkt einbettet (z. B. React/Vite mit `VITE_*`-Variablen). + +--- + +## Variablen setzen + +### Via Oberfläche + +1. Anwendung öffnen → **"Umgebungsvariablen"** +2. **"Variable hinzufügen"** → Key und Value eintragen +3. Bei sensiblen Werten: **"Geheimnis"**-Toggle aktivieren +4. **"Speichern"** — beim nächsten Deployment aktiv + +### Via API + +```bash +# Variablen einer Anwendung aktualisieren (PATCH überschreibt den kompletten Satz) +curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/ \ + -H "Authorization: Bearer $COOLIFY_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "environment_variables": "DATABASE_URL=postgresql://user:pass@host:5432/db\nLOG_LEVEL=info\nAPP_ENV=production" + }' +``` + +--- + +## Secrets — sicherer Umgang + +Secrets sind Variablen, deren Werte besonders sensibel sind (Passwörter, API-Keys, Private Keys). + +**Empfehlungen:** + +- Secrets **niemals** in Git einchecken (`.gitignore` für `.env`-Dateien) +- Secrets **niemals** in Logs ausgeben +- Secrets **rotieren**, wenn Zugang eines Teammitglieds erlischt +- Nur so viele Secrets wie nötig — je Anwendung nur die tatsächlich benötigten Werte + +```bash +# Beispiel: .env-Datei (lokal / für Entwicklung, niemals committen!) +DATABASE_URL="postgresql://dev:devpass@localhost:5432/myapp" +JWT_SECRET="lokaler-dev-secret-nicht-produktionsreif" +``` + +--- + +## Best Practices + +### 12-Factor-App-Prinzip + +Folgt dem [12-Factor-App](https://12factor.net/de/config)-Prinzip: Alle Konfiguration, die sich zwischen Umgebungen unterscheidet, kommt aus Umgebungsvariablen — nicht aus dem Code. + +``` +# Gut: Konfiguration aus der Umgebung +const dbUrl = process.env.DATABASE_URL; + +# Schlecht: Konfiguration im Code +const dbUrl = "postgresql://user:pass@prod-server:5432/db"; +``` + +### Unterschied Entwicklung / Produktion + +| Umgebung | Empfehlung | +|---|---| +| Lokale Entwicklung | `.env`-Datei (niemals committen) | +| Staging / Produktion | Variablen in der Plattform hinterlegen | + +### `.env.example` für Dokumentation + +Checkt eine `.env.example` ins Repository ein, die alle Variablen mit Erklärungen, aber ohne echte Werte enthält: + +```bash +# .env.example — In Git einchecken! +# Beschreibung: Verbindungsstring zur Datenbank +DATABASE_URL= + +# API-Schlüssel für externen Service +EXTERNAL_API_KEY= + +# Loglevel: debug | info | warn | error +LOG_LEVEL=info +``` + +--- + +## Variablen im Build-Log + +Variablen, die als **Geheimnis** markiert sind, werden in Build-Logs automatisch maskiert (`***`). + +:::note +Keine Variable wird automatisch versteckt, wenn sie **nicht** als Geheimnis markiert ist. +Achtet darauf, sensible Werte korrekt zu klassifizieren. +::: diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx new file mode 100644 index 0000000..c20b927 --- /dev/null +++ b/src/content/docs/index.mdx @@ -0,0 +1,65 @@ +--- +title: BTC MAIN · Managed AI Now +description: Der AI Application Layer der BTC AG — Ihre Plattform für Deployment, Betrieb und Skalierung moderner Anwendungen. +template: splash +hero: + tagline: Anwendungen deployen. Pipelines automatisieren. Infrastruktur vergessen. + image: + file: ../../assets/logo.svg + actions: + - text: Schnellstart + link: /einstieg/schnellstart/ + icon: right-arrow + variant: primary + - text: Einführung lesen + link: /einstieg/einfuehrung/ + icon: open-book + variant: secondary +--- + +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +## Was ist der AI Application Layer? + +Der **AI Application Layer** ist die zentrale Deployment-Plattform der BTC AG im Rahmen von **BTC MAIN — Managed AI Now**. +Er ermöglicht es Entwicklungs- und Betriebsteams, Anwendungen schnell, sicher und reproduzierbar bereitzustellen — +ohne sich um die darunter liegende Infrastruktur kümmern zu müssen. + + + + Git-basiertes Deployment in Sekunden. Docker-Container, statische Seiten oder Server-Anwendungen — + einfach in das Repository pushen, der Rest passiert automatisch. + + + CI/CD-Workflows mit Gitea-Webhooks oder Gitea Actions. Vollständige Pipeline von + Commit bis Livegang — konfigurierbar, nachvollziehbar, wiederholbar. + + + Logs, Deployment-Historie und Ressourcenstatus direkt in der Plattform. + Kein SSH auf Produktionssysteme mehr nötig. + + + Betrieben auf STACKIT IaaS in der Region Frankfurt (EU) — vollständig unter Kontrolle der BTC AG, + DSGVO-konform, keine Public-Cloud-Abhängigkeit. + + + +--- + +## Einstieg + + + + diff --git a/src/content/docs/referenz/faq.md b/src/content/docs/referenz/faq.md new file mode 100644 index 0000000..5c199cb --- /dev/null +++ b/src/content/docs/referenz/faq.md @@ -0,0 +1,99 @@ +--- +title: FAQ +description: Häufig gestellte Fragen zum AI Application Layer. +sidebar: + order: 2 +--- + +## Allgemein + +### Was kostet die Nutzung des AI Application Layer? + +Die Kosten werden intern über die BTC AG verrechnet. Details zur Kostenzuordnung klären mit dem Platform-Team oder über den IT-Servicedesk. + +### Wer kann die Plattform nutzen? + +Aktuell steht die Plattform internen Teams der BTC AG zur Verfügung. Ein Self-Service-Onboarding ist in Planung. + +### Welche Anwendungstypen werden unterstützt? + +Alles, was in einem Docker-Container läuft: Web-APIs, Frontends, Background-Worker, Batch-Jobs, statische Sites und mehr. + +### Ist die Plattform DSGVO-konform? + +Ja. Alle Daten verbleiben in der Region Frankfurt (EU01) auf STACKIT-Infrastruktur, die vollständig von der BTC AG betrieben wird. Es gibt keine Public-Cloud-Abhängigkeit. + +--- + +## Deployment & Build + +### Mein Build schlägt fehl — wo finde ich den Fehler? + +Im Deployment-Log der Anwendung: Anwendung → **"Deployments"** → Deployment auswählen → **"Log anzeigen"**. +Der Log zeigt exakt, bei welchem Schritt der Fehler aufgetreten ist. + +### Kann ich einen bestimmten Commit deployen, nicht nur den neuesten? + +Aktuell wird immer der HEAD des konfigurierten Branch deployt. Das Deployment eines spezifischen Commits ist über die API möglich, wenn der Branch auf diesen Commit zeigt. + +### Wie lange dauert ein typisches Deployment? + +Das hängt vom Build ab. Einfache Node.js-Apps bauen in 30–60 Sekunden, größere Images mit Compile-Schritten können 2–5 Minuten brauchen. Nach dem Build ist der neue Container innerhalb von Sekunden live. + +### Was passiert mit der laufenden App während eines Deployments? + +Die laufende Version bleibt aktiv, bis der neue Container bereit ist. Dann wird der Traffic nahtlos umgeschaltet. Es gibt keine Downtime. + +### Kann ich einen Deploy rückgängig machen? + +Nicht direkt als "Rollback"-Funktion. Aber: Da alle Deployments in der Historie gespeichert sind, könnt ihr den alten Commit taggen und erneut deployen. + +--- + +## Domains & TLS + +### Bekomme ich automatisch ein HTTPS-Zertifikat? + +Ja. Sobald die Domain korrekt in der Anwendung eingetragen ist und der DNS-Eintrag auf die Plattform zeigt, wird das Zertifikat automatisch über Let's Encrypt ausgestellt. + +### Kann ich eine eigene Domain (nicht btc-ag.cloud) verwenden? + +Ja. Ihr müsst einen CNAME auf den Plattform-Eintrittspunkt setzen. Details: [Custom Domains](/guides/custom-domains/). + +### Mein Zertifikat läuft ab — muss ich etwas tun? + +Nein. Let's Encrypt-Zertifikate werden automatisch 30 Tage vor Ablauf erneuert. + +--- + +## API & Automatisierung + +### Wo finde ich meine UUIDs (Projekt, Server, App)? + +- **Projekt-UUID**: In der Plattform unter Projekteinstellungen +- **Server-UUID**: Über `GET /api/v1/servers` +- **App-UUID**: Über `GET /api/v1/applications` oder in der App-Detailansicht + +### Kann ich die Plattform vollständig per API steuern (kein UI)? + +Ja. Alle Funktionen der Plattform sind über die REST-API verfügbar. + +### Gibt es SDKs oder CLI-Tools? + +Aktuell keine offiziellen SDKs seitens der Plattform. Die REST-API lässt sich mit beliebigen HTTP-Clients nutzen (`curl`, `httpx`, `axios`, ...). + +--- + +## Betrieb + +### Wie bekomme ich Support? + +Über den internen IT-Servicedesk der BTC AG oder direkt beim Platform-Team. + +### Wo melde ich Bugs oder Feature-Requests? + +Im internen Ticketsystem der BTC AG. Für direkte Rückmeldungen: Platform-Team kontaktieren. + +### Gibt es Wartungsfenster? + +Geplante Wartungen werden im Voraus angekündigt. Notfall-Wartungen können ohne Vorankündigung stattfinden. diff --git a/src/content/docs/referenz/tech-stack.md b/src/content/docs/referenz/tech-stack.md new file mode 100644 index 0000000..1db4345 --- /dev/null +++ b/src/content/docs/referenz/tech-stack.md @@ -0,0 +1,80 @@ +--- +title: Tech Stack +description: Die Technologien hinter dem AI Application Layer — Plattform-Komponenten und unterstützte Runtimes. +sidebar: + order: 1 +--- + +## Plattform-Komponenten + +| Komponente | Technologie | Aufgabe | +|---|---|---| +| **Deployment-Orchestrierung** | Coolify | Deployment-Steuerung, UI, API, Build-Pipeline | +| **Container-Runtime** | Docker | Ausführung aller Anwendungen | +| **Reverse Proxy** | Traefik | HTTPS-Routing, TLS-Terminierung | +| **TLS-Zertifikate** | Let's Encrypt | Automatische Ausstellung und Erneuerung | +| **Versionsverwaltung** | Gitea | Self-hosted Git-Service | +| **Infrastruktur** | STACKIT IaaS | Virtuelle Maschinen, Region Frankfurt (EU01) | +| **Infrastructure as Code** | Terraform | Provisionierung der Infrastruktur | + +--- + +## Unterstützte Build-Profile + +### Dockerfile (empfohlen) + +Jede Anwendung mit einem `Dockerfile` im Repository-Root wird unterstützt. +Damit ist jede Sprache, jedes Framework und jede Laufzeit möglich. + +``` +Sprachen: Python, Node.js, Go, Java, Rust, PHP, Ruby, .NET, ... +``` + +### Nixpacks + +Nixpacks erkennt die Projektstruktur automatisch und erstellt ein passendes Build-Profil — kein `Dockerfile` nötig. + +Gut unterstützte Ökosysteme: + +| Sprache / Framework | Erkennungsmerkmal | +|---|---| +| Node.js | `package.json` | +| Python | `requirements.txt`, `Pipfile`, `pyproject.toml` | +| Go | `go.mod` | +| Ruby | `Gemfile` | +| PHP | `composer.json` | +| Java/Kotlin | `pom.xml`, `build.gradle` | +| Rust | `Cargo.toml` | + +### Static + +Für statische Websites (HTML/CSS/JS) ohne Backend. +Dateien werden direkt via nginx ausgeliefert. + +--- + +## Betriebsumgebung + +| Eigenschaft | Wert | +|---|---| +| **Cloud-Provider** | STACKIT IaaS | +| **Region** | eu01 (Frankfurt, Deutschland) | +| **Betreiber** | BTC AG | +| **Datenschutz** | DSGVO-konform, kein Datenabfluss in Public Clouds | + +--- + +## Versionspolitik + +Die Plattform wird regelmäßig aktualisiert. Breaking Changes werden im Voraus angekündigt. +Für Versionshinweise und geplante Wartungsfenster wendet euch an das Platform-Team. + +--- + +## Externe Links + +- [Coolify Dokumentation](https://coolify.io/docs) +- [Docker Dokumentation](https://docs.docker.com) +- [Traefik Dokumentation](https://doc.traefik.io/traefik/) +- [Gitea Dokumentation](https://docs.gitea.com) +- [STACKIT IaaS Dokumentation](https://docs.stackit.cloud/stackit/en/virtual-machines-86444220.html) diff --git a/src/styles/custom.css b/src/styles/custom.css new file mode 100644 index 0000000..1de3510 --- /dev/null +++ b/src/styles/custom.css @@ -0,0 +1,74 @@ +/* BTC MAIN - Managed AI Now: Brand Colors */ +:root { + --sl-color-accent-low: #0c1a3b; + --sl-color-accent: #1a56db; + --sl-color-accent-high: #93c5fd; + + --sl-font: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --sl-font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace; +} + +:root[data-theme='dark'] { + --sl-color-accent-low: #0c1e4a; + --sl-color-accent: #3b82f6; + --sl-color-accent-high: #bfdbfe; + --sl-color-bg: #0d1117; + --sl-color-bg-nav: #161b22; + --sl-color-bg-sidebar: #0d1117; + --sl-color-hairline-light: #21262d; + --sl-color-hairline: #30363d; +} + +/* Hero-Page Tweaks */ +.hero { + padding-block: 4rem; +} + +.hero > .hero-html h1 { + font-size: clamp(2rem, 5vw, 3.5rem); + font-weight: 800; + line-height: 1.1; +} + +/* Sidebar Badge Styling */ +.sl-badge { + border-radius: 4px; + font-size: 0.7rem; + font-weight: 600; + letter-spacing: 0.04em; + text-transform: uppercase; +} + +/* Code Blocks */ +pre { + border: 1px solid var(--sl-color-hairline); + border-radius: 8px; +} + +/* API Endpoint Tables */ +table code { + background: var(--sl-color-bg-inline-code); + border-radius: 4px; + padding: 0.1em 0.4em; + font-size: 0.875em; +} + +/* Aside / Callouts */ +.starlight-aside { + border-radius: 8px; +} + +/* Custom Header Gradient */ +.site-title { + font-weight: 700; + letter-spacing: -0.02em; +} + +/* Footer */ +.social-icons a { + opacity: 0.7; + transition: opacity 0.2s; +} +.social-icons a:hover { + opacity: 1; +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..8bf91d3 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +}