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 <noreply@anthropic.com>
This commit is contained in:
Thomas Soring
6
.gitignore
vendored
Normal file
6
.gitignore
vendored
Normal file
@@ -0,0 +1,6 @@
|
||||
dist/
|
||||
node_modules/
|
||||
.astro/
|
||||
.env
|
||||
.env.*
|
||||
*.local
|
||||
12
Dockerfile
Normal file
12
Dockerfile
Normal file
@@ -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;"]
|
||||
66
astro.config.mjs
Normal file
66
astro.config.mjs
Normal file
@@ -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: {},
|
||||
}),
|
||||
],
|
||||
});
|
||||
32
nginx.conf
Normal file
32
nginx.conf
Normal file
@@ -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";
|
||||
}
|
||||
17
package.json
Normal file
17
package.json
Normal file
@@ -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"
|
||||
}
|
||||
}
|
||||
7
src/assets/logo.svg
Normal file
7
src/assets/logo.svg
Normal file
@@ -0,0 +1,7 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 36" fill="none">
|
||||
<!-- AI Hexagon Icon -->
|
||||
<polygon points="16,2 28,9 28,23 16,30 4,23 4,9" fill="#1a56db" opacity="0.15" stroke="#1a56db" stroke-width="1.5"/>
|
||||
<text x="10" y="22" font-family="monospace" font-size="11" font-weight="700" fill="#1a56db">AI</text>
|
||||
<!-- Wordmark -->
|
||||
<text x="38" y="25" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="16" font-weight="800" fill="currentColor" letter-spacing="-0.5">BTC MAIN</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 536 B |
6
src/content/config.ts
Normal file
6
src/content/config.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
import { defineCollection } from 'astro:content';
|
||||
import { docsSchema } from '@astrojs/starlight/schema';
|
||||
|
||||
export const collections = {
|
||||
docs: defineCollection({ schema: docsSchema() }),
|
||||
};
|
||||
210
src/content/docs/api/applications.mdx
Normal file
210
src/content/docs/api/applications.mdx
Normal file
@@ -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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Request">
|
||||
|
||||
```bash
|
||||
curl -s https://coolai.btc-ag.cloud/api/v1/applications \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Response">
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Einzelne Anwendung abrufen
|
||||
|
||||
```http
|
||||
GET /applications/{uuid}
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Request">
|
||||
|
||||
```bash
|
||||
curl -s https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Response">
|
||||
|
||||
```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 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Request">
|
||||
|
||||
```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": "<projekt-uuid>",
|
||||
"server_uuid": "<server-uuid>",
|
||||
"environment_name": "production",
|
||||
"private_key_uuid": "<deploy-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"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Response">
|
||||
|
||||
```json
|
||||
{
|
||||
"uuid": "newly-created-uuid",
|
||||
"message": "Application created."
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Domain ändern">
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"fqdn": "https://neue-domain.btc-ag.cloud"}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Env-Vars setzen">
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"environment_variables": "DATABASE_URL=postgresql://...\nLOG_LEVEL=info"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Anwendung löschen
|
||||
|
||||
```http
|
||||
DELETE /applications/{uuid}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -s -X DELETE https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN"
|
||||
```
|
||||
|
||||
:::caution
|
||||
Das Löschen einer Anwendung stoppt den Container und entfernt alle zugehörigen Konfigurationen. Deployment-Historien bleiben erhalten.
|
||||
:::
|
||||
121
src/content/docs/api/authentifizierung.md
Normal file
121
src/content/docs/api/authentifizierung.md
Normal file
@@ -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 <euer-token>
|
||||
```
|
||||
|
||||
### Beispiel mit curl
|
||||
|
||||
```bash
|
||||
# Token als Umgebungsvariable (sicher)
|
||||
export COOLIFY_TOKEN="<euer-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."
|
||||
}
|
||||
```
|
||||
172
src/content/docs/api/deployments.md
Normal file
172
src/content/docs/api/deployments.md
Normal file
@@ -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=<app-uuid>&force=false" \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN"
|
||||
|
||||
# Force-Rebuild (kein Cache)
|
||||
curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-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/<app-uuid> \
|
||||
-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/<deployment-uuid> \
|
||||
-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/<deployment-uuid>/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="<app-uuid>"
|
||||
COOLIFY_TOKEN="<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
|
||||
```
|
||||
102
src/content/docs/api/uebersicht.md
Normal file
102
src/content/docs/api/uebersicht.md
Normal file
@@ -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 <euer-api-token>
|
||||
```
|
||||
|
||||
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**
|
||||
112
src/content/docs/einstieg/einfuehrung.md
Normal file
112
src/content/docs/einstieg/einfuehrung.md
Normal file
@@ -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.
|
||||
:::
|
||||
134
src/content/docs/einstieg/konzepte.md
Normal file
134
src/content/docs/einstieg/konzepte.md
Normal file
@@ -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.
|
||||
113
src/content/docs/einstieg/schnellstart.mdx
Normal file
113
src/content/docs/einstieg/schnellstart.mdx
Normal file
@@ -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
|
||||
|
||||
<Steps>
|
||||
|
||||
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"**
|
||||
|
||||
<Aside type="tip">
|
||||
Für Repositories auf `git.coolai.btc-ag.cloud` wählt **"Privates Repository mit Deploy-Key"**.
|
||||
</Aside>
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
<Aside type="caution">
|
||||
Sensible Werte (Passwörter, Tokens) als **Secret** markieren — sie werden dann nicht im Klartext angezeigt.
|
||||
</Aside>
|
||||
|
||||
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
|
||||
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
173
src/content/docs/guides/app-deployen.mdx
Normal file
173
src/content/docs/guides/app-deployen.mdx
Normal file
@@ -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
|
||||
|
||||
<Steps>
|
||||
|
||||
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.
|
||||
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Deployment via API
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="App anlegen">
|
||||
|
||||
```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": "<projekt-uuid>",
|
||||
"server_uuid": "<server-uuid>",
|
||||
"environment_name": "production",
|
||||
"private_key_uuid": "<deploy-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"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Deployment auslösen">
|
||||
|
||||
```bash
|
||||
# Deployment triggern (UUID aus dem App-Anlegen-Response)
|
||||
curl -s -X GET \
|
||||
"https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=false" \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Status prüfen">
|
||||
|
||||
```bash
|
||||
# Deployment-Status abfragen
|
||||
curl -s https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN" \
|
||||
| jq '.status'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 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/<app-uuid> \
|
||||
-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 |
|
||||
|
||||
<Aside type="tip">
|
||||
Der Build-Log ist immer der erste Anlaufpunkt bei Problemen. Er zeigt exakt, bei welchem Schritt der Build fehlgeschlagen ist.
|
||||
</Aside>
|
||||
157
src/content/docs/guides/cicd-pipelines.md
Normal file
157
src/content/docs/guides/cicd-pipelines.md
Normal file
@@ -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/<app-uuid> \
|
||||
-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=<app-uuid>&force=false` |
|
||||
| HTTP-Methode | `POST` |
|
||||
| Content Type | `application/json` |
|
||||
| Authorization-Header | `Bearer <euer-api-token>` |
|
||||
| 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="<euer-gitea-token>"
|
||||
GITEA_URL="https://git.coolai.btc-ag.cloud"
|
||||
REPO_OWNER="meinteam"
|
||||
REPO_NAME="meine-app"
|
||||
APP_UUID="<app-uuid>"
|
||||
COOLIFY_TOKEN="<euer-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/<app-uuid>" \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN" \
|
||||
| jq 'first | {status: .status, started: .created_at}'
|
||||
```
|
||||
87
src/content/docs/guides/custom-domains.md
Normal file
87
src/content/docs/guides/custom-domains.md
Normal file
@@ -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/<app-uuid> \
|
||||
-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 |
|
||||
134
src/content/docs/guides/logs-monitoring.md
Normal file
134
src/content/docs/guides/logs-monitoring.md
Normal file
@@ -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/<app-uuid> \
|
||||
-H "Authorization: Bearer $COOLIFY_TOKEN" \
|
||||
| jq '.[] | {id, status, created_at}'
|
||||
|
||||
# Log eines einzelnen Deployments
|
||||
curl -s https://coolai.btc-ag.cloud/api/v1/deployments/<deployment-uuid> \
|
||||
-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/<app-uuid>/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/<server-uuid>/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/<deployment-uuid>/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.
|
||||
:::
|
||||
111
src/content/docs/guides/umgebungsvariablen.md
Normal file
111
src/content/docs/guides/umgebungsvariablen.md
Normal file
@@ -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/<app-uuid> \
|
||||
-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.
|
||||
:::
|
||||
65
src/content/docs/index.mdx
Normal file
65
src/content/docs/index.mdx
Normal file
@@ -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.
|
||||
|
||||
<CardGrid stagger>
|
||||
<Card title="Apps deployen" icon="rocket">
|
||||
Git-basiertes Deployment in Sekunden. Docker-Container, statische Seiten oder Server-Anwendungen —
|
||||
einfach in das Repository pushen, der Rest passiert automatisch.
|
||||
</Card>
|
||||
<Card title="Pipelines automatisieren" icon="setting">
|
||||
CI/CD-Workflows mit Gitea-Webhooks oder Gitea Actions. Vollständige Pipeline von
|
||||
Commit bis Livegang — konfigurierbar, nachvollziehbar, wiederholbar.
|
||||
</Card>
|
||||
<Card title="Betrieb im Blick" icon="magnifier">
|
||||
Logs, Deployment-Historie und Ressourcenstatus direkt in der Plattform.
|
||||
Kein SSH auf Produktionssysteme mehr nötig.
|
||||
</Card>
|
||||
<Card title="Sicher & souverän" icon="shield">
|
||||
Betrieben auf STACKIT IaaS in der Region Frankfurt (EU) — vollständig unter Kontrolle der BTC AG,
|
||||
DSGVO-konform, keine Public-Cloud-Abhängigkeit.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
---
|
||||
|
||||
## Einstieg
|
||||
|
||||
<LinkCard
|
||||
title="Einführung"
|
||||
description="Was ist der AI Application Layer? Architektur, Einsatzbereiche und Zielgruppen."
|
||||
href="/einstieg/einfuehrung/"
|
||||
/>
|
||||
<LinkCard
|
||||
title="Schnellstart"
|
||||
description="In wenigen Schritten zur ersten deployten Anwendung."
|
||||
href="/einstieg/schnellstart/"
|
||||
/>
|
||||
<LinkCard
|
||||
title="Kernkonzepte"
|
||||
description="Projekte, Anwendungen, Deployments, Domains — die wichtigsten Begriffe erklärt."
|
||||
href="/einstieg/konzepte/"
|
||||
/>
|
||||
99
src/content/docs/referenz/faq.md
Normal file
99
src/content/docs/referenz/faq.md
Normal file
@@ -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.
|
||||
80
src/content/docs/referenz/tech-stack.md
Normal file
80
src/content/docs/referenz/tech-stack.md
Normal file
@@ -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)
|
||||
74
src/styles/custom.css
Normal file
74
src/styles/custom.css
Normal file
@@ -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;
|
||||
}
|
||||
5
tsconfig.json
Normal file
5
tsconfig.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"extends": "astro/tsconfigs/strict",
|
||||
"include": [".astro/types.d.ts", "**/*"],
|
||||
"exclude": ["dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user