Kernkonzepte

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

klont das Repository am konfigurierten Branch/Commit,
baut das Docker-Image,
startet einen neuen Container,
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

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.

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

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.