Self-Hosting

Eine selbst gehostete Installation betreibt die Ephemeral-Engine und das Ausführungs-Dashboard auf einem Host unter Ihrer Kontrolle, mit Workern in microVMs in Ihrem eigenen AWS-Konto und Ihrem eigenen Modellanbieter. Sie erhalten ein Docker-Image und seine Dokumentation; das Image exportiert alle weiteren benötigten Dateien. Sie benötigt eine Bereitstellungslizenz von Ephemeral.

Was Sie betreiben

Die Kunden-Website, Konten und die Abrechnung sind nicht Teil einer selbst gehosteten Installation, ebenso wenig Quellcode. Personen melden sich mit einem Engine-API-Schlüssel am Dashboard an.

Das Image enthält die vollständige Betreiberanleitung. Die folgenden Schritte fassen sie zusammen; genaue Befehle, erwartete Ausgaben, Upgrades, Backups und Fehlerbehebung finden Sie in der Anleitung:

docker run --rm ephemer.al/ephemeral/self-hosted:VERSION setup docs > SELF-HOSTING.md

Bevor Sie beginnen

• Docker mit Docker Compose 2.24 oder neuer sowie AWS CLI v2 mit dem Session-Manager-Plugin.
• Ein AWS-Konto in einer Region mit Lambda-microVMs und die Berechtigung, einen CloudFormation-Stack mit IAM-Rollen zu erstellen.
• Ein Domainname, den Sie auf den Host verweisen können.
• Ein OpenAI-kompatibler Inferenz-Endpunkt und API-Schlüssel.
• Ein Anspruch (Entitlement) für Ihre Organisation. Ephemeral erteilt ihn nach einer Vereinbarung; siehe Bereitstellungslizenzen.

Installation

1. Installation registrieren

   Öffnen Sie im Kundenportal Bereitstellungen und registrieren Sie diese Installation mit einem Namen, etwa production-eu. Ephemeral erzeugt ihre Maschinen-ID und das Lizenz-Token. Wählen Sie Lizenzdatei herunterladen, um Token, Maschinen-ID und Bereitstellungs-ID aufzubewahren; das Token wird nur einmal angezeigt.

2. Image herunterladen

   Melden Sie sich an der Registry mit der Bereitstellungs-ID als Benutzername und dem Lizenz-Token als Passwort an und laden Sie dann ein Release. Versionen haben kein führendes v.

   Terminal

   export EPHEMERAL_VERSION=0.1.0
   read -rs LICENSE_TOKEN
   printf '%s' "$LICENSE_TOKEN" | docker login ephemer.al -u dep_YOUR_DEPLOYMENT_ID --password-stdin
   docker pull ephemer.al/ephemeral/self-hosted:$EPHEMERAL_VERSION

3. Installationsdateien exportieren

   Terminal

   mkdir -p ephemeral && cd ephemeral
   docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/out" \
     ephemer.al/ephemeral/self-hosted:$EPHEMERAL_VERSION setup all /out

   Datei	Zweck
   compose.yaml	PostgreSQL, die Anwendung und Caddy, auf dieses Release festgelegt
   compose.evaluation.yaml	Override zum Ausprobieren auf einem Rechner ohne AWS
   Caddyfile	Ingress-Routen
   .env	Konfiguration mit neu erzeugten Geheimnissen. Ein späterer Export überschreibt sie nie
   ephemeral-aws.yaml	CloudFormation-Template für die AWS-Ressourcen
   ephemeral-worker-VERSION.zip	Der kompilierte Worker, den AWS zum microVM-Image baut
   SELF-HOSTING.md	Die Betreiberanleitung

4. AWS-Ressourcen erstellen

   Laden Sie die Worker-ZIP-Datei in einen privaten S3-Bucket Ihres Kontos hoch und erstellen Sie dann den Stack. Er legt ein VPC mit isoliertem Worker-Subnetz, eine DNS-Firewall, das microVM-Image und den Netzwerk-Connector, einen verschlüsselten Storage-Bucket, die IAM-Rolle des Hosts mit minimalen Rechten und standardmäßig einen t4g.small-Host mit Amazon Linux, Elastic IP und verschlüsseltem Datenvolume an. Das Bauen des Worker-Images dauert 15 bis 30 Minuten, und der Stack erzeugt kostenpflichtige Ressourcen.

   Terminal

   aws s3 cp "ephemeral-worker-$EPHEMERAL_VERSION.zip" "s3://YOUR_ARTIFACT_BUCKET/"
   aws cloudformation create-stack --stack-name ephemeral \
     --template-body file://ephemeral-aws.yaml --capabilities CAPABILITY_IAM \
     --parameters ParameterKey=Domain,ParameterValue=ephemeral.example.com \
       ParameterKey=WorkerArtifactBucket,ParameterValue=YOUR_ARTIFACT_BUCKET \
       ParameterKey=WorkerArtifactKey,ParameterValue="ephemeral-worker-$EPHEMERAL_VERSION.zip" \
       ParameterKey=HostImageId,ParameterValue=AL2023_ARM64_AMI
   aws cloudformation wait stack-create-complete --stack-name ephemeral
   aws cloudformation describe-stacks --stack-name ephemeral \
     --query "Stacks[0].Outputs[?OutputKey=='EngineEnvironment'].OutputValue" --output text | tr ' ' '\n'

   Der letzte Befehl gibt die AWS-Einstellungen für die Engine aus. Verweisen Sie den DNS-A-Eintrag Ihrer Domain auf die Stack-Ausgabe HostPublicIp.

5. Host konfigurieren

   Verbinden Sie sich mit aws ssm start-session --target und der Stack-Ausgabe HostInstanceId, wiederholen Sie dann die Registry-Anmeldung und den Export in /srv/ephemeral/install. Bearbeiten Sie diese Einträge in .env:

   Einstellung	Wert
   EPHEMERAL_DOMAIN	Ihr Hostname, etwa ephemeral.example.com
   EPHEMERAL_LICENSE_TOKEN	Das Token aus dem ersten Schritt
   EPHEMERAL_MACHINE_ID	Die Maschinen-ID aus dem ersten Schritt, genau wie registriert
   INFERENCE_BASE_URL	Ihr OpenAI-kompatibler Endpunkt
   INFERENCE_API_KEY	Sein API-Schlüssel
   EPHEMERAL_DEFAULT_MODEL	Das Modell, das Ausführungen verwenden, wenn sie keines nennen
   AWS-Einstellungen	Die fünf Zeilen, die der Stack ausgegeben hat: AWS_REGION, EPHEMERAL_S3_BUCKET und drei EPHEMERAL_MICROVM_…-Werte

   Der Export hat den Master-Verschlüsselungsschlüssel, den Bootstrap-Admin-Schlüssel und das Datenbankpasswort erzeugt. Bewahren Sie eine Kopie von .env in Ihrem Secret-Manager auf; ohne den Master-Schlüssel lassen sich gespeicherte Zugangsdaten und Ausführungs-Payloads nicht lesen. Das Instanzprofil des Hosts stellt die AWS-Zugangsdaten bereit.

6. Installation starten

   Caddy bezieht das HTTPS-Zertifikat. PostgreSQL und die internen APIs werden nicht veröffentlicht.

   Terminal

   docker compose pull
   docker compose up -d

   Die Engine validiert die Lizenz beim Start und startet nicht, wenn sie ungültig ist oder die konfigurierte Parallelität sie überschreitet.

7. Erste Organisation erstellen

   Eine neue Installation hat keine API-Schlüssel. Führen Sie dies einmal im Installationsverzeichnis aus und ersetzen Sie my-organization durch eine Organisations-ID Ihrer Wahl. Der Befehl liest den Bootstrap-Schlüssel im Container, sodass der Schlüssel nicht in Ihrem Shell-Verlauf landet.

   Terminal

   docker compose exec -T app node --input-type=module - <<'NODE'
   if (process.env.EPHEMERAL_MODE !== 'self-hosted') {
     throw new Error('Bootstrap requires EPHEMERAL_MODE=self-hosted');
   }
   const adminKey = process.env.EPHEMERAL_ADMIN_KEY;
   if (!adminKey) throw new Error('EPHEMERAL_ADMIN_KEY is not configured');
   const response = await fetch('http://127.0.0.1:8080/admin/organizations', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${adminKey}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({id: 'my-organization'}),
   });
   const result = await response.json();
   if (!response.ok) throw new Error(result.error || `Bootstrap failed (${response.status})`);
   console.log(JSON.stringify(result, null, 2));
   NODE

   Die Antwort enthält die Organisations-id, key_id und role des neuen Inhaberschlüssels sowie den key selbst, der mit eph_ beginnt. Speichern Sie den Schlüssel jetzt; er lässt sich später nicht mehr abrufen. Führen Sie den Befehl erneut für eine Organisation aus, die einen aktiven Schlüssel hat, liefert er 409.

8. Anmelden

   Öffnen Sie Ihre HTTPS-Adresse und geben Sie den Schlüssel unter API-Schlüssel der Organisation ein. Weitere member- und admin-Schlüssel erstellen Sie unter API-Schlüssel. Der Bootstrap-Admin-Schlüssel aus der Konfigurationsdatei erstellt nur Organisationen; er kann sich nicht anmelden und die API nicht aufrufen.

Auf einem Rechner ausprobieren

Ohne AWS fügen Sie den Evaluierungs-Override hinzu. Agenten laufen dann mit dem lokalen Runner im Anwendungscontainer, und das Dashboard wird nur über unverschlüsseltes HTTP unter http://localhost:8000 ausgeliefert. Eine Lizenz ist weiterhin erforderlich; registrieren Sie dafür eine separate Bereitstellung.

docker compose -f compose.yaml -f compose.evaluation.yaml up -d

Unterschiede zum gehosteten Dienst

Updates und Backups

Für ein Upgrade laden Sie die Worker-ZIP-Datei des neuen Releases hoch und aktualisieren den Stack mit ihrem Schlüssel. Exportieren Sie dann auf dem Host die Dateien des neuen Releases, setzen Sie EPHEMERAL_VERSION und die neue EPHEMERAL_MICROVM_IMAGE_VERSION in .env und führen Sie docker compose up -d aus. Laufende Ausführungen haben bis zu fünf Minuten Zeit zum Abschluss; danach noch aktive Ausführungen werden als interrupted markiert und nicht wiederholt, sodass externe Aktionen nie erneut ausgeführt werden. Datenbankmigrationen laufen automatisch.

Sichern Sie sowohl die Datenbank als auch den Master-Verschlüsselungsschlüssel. Geht der Master-Schlüssel verloren, sind gespeicherte Verbindungszugangsdaten und Ausführungs-Payloads nicht mehr lesbar. Der vom Stack erstellte Host sichert die Datenbank täglich in seinen S3-Bucket.