Auto-hébergement

Une installation auto-hébergée fait tourner le moteur Ephemeral et le tableau de bord d'exécution sur un hôte que vous contrôlez, avec des workers dans des microVM de votre propre compte AWS et votre propre fournisseur de modèles. Vous recevez une image Docker et sa documentation ; l'image exporte tous les autres fichiers dont vous avez besoin. Elle nécessite une licence de déploiement délivrée par Ephemeral.

Ce que vous exploitez

Le site client, les comptes et la facturation ne font pas partie d'une installation auto-hébergée, pas plus que le code source. Les utilisateurs se connectent au tableau de bord avec une clé API du moteur.

L'image contient le guide complet de l'opérateur. Les étapes ci-dessous en donnent un résumé ; suivez le guide pour les commandes exactes, les sorties attendues, les mises à niveau, les sauvegardes et le dépannage :

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

Avant de commencer

• Docker avec Docker Compose 2.24 ou plus récent, et AWS CLI v2 avec le plugin Session Manager.
• Un compte AWS dans une région disposant des microVM Lambda, et l'autorisation de créer une pile CloudFormation avec des rôles IAM.
• Un nom de domaine que vous pouvez faire pointer vers l'hôte.
• Un endpoint d'inférence compatible OpenAI et sa clé API.
• Un droit d'utilisation pour votre organisation. Ephemeral l'accorde après un accord ; voir licences de déploiement.

Installer

1. Enregistrer l'installation

   Dans le portail client, ouvrez Déploiements et enregistrez cette installation avec un nom, par exemple production-eu. Ephemeral crée son ID de machine et son jeton de licence. Choisissez Télécharger le fichier de licence pour conserver le jeton, l'ID de machine et l'ID de déploiement ; le jeton n'est affiché qu'une fois.

2. Récupérer l'image

   Connectez-vous au registre avec l'ID de déploiement comme nom d'utilisateur et le jeton de licence comme mot de passe, puis récupérez une version. Les numéros de version n'ont pas de v initial.

   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. Exporter les fichiers d'installation

   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

   Fichier	Rôle
   compose.yaml	PostgreSQL, l'application et Caddy, figés sur cette version
   compose.evaluation.yaml	Surcharge pour l'essayer sur un seul ordinateur, sans AWS
   Caddyfile	Routes d'entrée
   .env	Configuration avec des secrets nouvellement générés. Un export ultérieur ne l'écrase jamais
   ephemeral-aws.yaml	Modèle CloudFormation pour les ressources AWS
   ephemeral-worker-VERSION.zip	Le worker compilé qu'AWS intègre à l'image de microVM
   SELF-HOSTING.md	Le guide de l'opérateur

4. Créer les ressources AWS

   Importez le ZIP du worker dans un bucket S3 privé de votre compte, puis créez la pile. Elle crée un VPC avec un sous-réseau isolé pour les workers, un pare-feu DNS, l'image de microVM et le connecteur réseau, un bucket de stockage chiffré, le rôle IAM à privilèges minimaux de l'hôte et, par défaut, un hôte Amazon Linux t4g.small avec une Elastic IP et un volume de données chiffré. La construction de l'image du worker prend 15 à 30 minutes, et la pile crée des ressources facturables.

   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'

   La dernière commande affiche les paramètres AWS du moteur. Faites pointer l'enregistrement DNS A de votre domaine vers la sortie de pile HostPublicIp.

5. Configurer l'hôte

   Connectez-vous avec aws ssm start-session --target et la sortie de pile HostInstanceId, puis répétez la connexion au registre et l'export dans /srv/ephemeral/install. Modifiez ces entrées dans .env :

   Paramètre	Valeur
   EPHEMERAL_DOMAIN	Votre nom d'hôte, par exemple ephemeral.example.com
   EPHEMERAL_LICENSE_TOKEN	Le jeton de la première étape
   EPHEMERAL_MACHINE_ID	L'ID de machine de la première étape, exactement tel qu'enregistré
   INFERENCE_BASE_URL	Votre endpoint compatible OpenAI
   INFERENCE_API_KEY	Sa clé API
   EPHEMERAL_DEFAULT_MODEL	Le modèle utilisé par les exécutions qui n'en désignent pas
   Paramètres AWS	Les cinq lignes affichées par la pile : AWS_REGION, EPHEMERAL_S3_BUCKET et trois valeurs EPHEMERAL_MICROVM_…

   L'export a généré la clé maître de chiffrement, la clé admin d'amorçage et le mot de passe de la base de données. Conservez une copie de .env dans votre gestionnaire de secrets ; sans la clé maître, les identifiants stockés et les données d'exécution sont illisibles. Le profil d'instance de l'hôte fournit les identifiants AWS.

6. Démarrer l'installation

   Caddy obtient le certificat HTTPS. PostgreSQL et les API internes ne sont pas publiés.

   Terminal

   docker compose pull
   docker compose up -d

   Le moteur valide la licence au démarrage et refuse de démarrer si elle est invalide ou si la concurrence configurée la dépasse.

7. Créer la première organisation

   Une nouvelle installation n'a aucune clé API. Exécutez ceci une fois dans le répertoire d'installation, en remplaçant my-organization par l'ID d'organisation de votre choix. La commande lit la clé d'amorçage à l'intérieur du conteneur : la clé reste ainsi absente de l'historique de votre shell.

   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

   La réponse contient l'id de l'organisation, le key_id et le role de la nouvelle clé de propriétaire, ainsi que la key elle-même, qui commence par eph_. Conservez la clé maintenant ; elle ne peut pas être récupérée plus tard. Relancer la commande pour une organisation qui a une clé active renvoie 409.

8. Se connecter

   Ouvrez votre adresse HTTPS et saisissez la clé sous Clé API d'organisation. Créez d'autres clés member et admin sous Clés API. La clé admin d'amorçage du fichier de configuration ne sert qu'à créer des organisations ; elle ne peut ni se connecter ni appeler l'API.

Essayer sur un seul ordinateur

Sans AWS, ajoutez la surcharge d'évaluation. Les agents s'exécutent alors dans le conteneur applicatif avec le runner local, et le tableau de bord est servi en HTTP simple à l'adresse http://localhost:8000 uniquement. Une licence reste nécessaire ; enregistrez-y un déploiement distinct.

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

Différences avec le service hébergé

Mises à jour et sauvegardes

Pour mettre à niveau, importez le ZIP du worker de la nouvelle version et mettez à jour la pile avec sa clé. Ensuite, sur l'hôte, exportez les fichiers de la nouvelle version, définissez EPHEMERAL_VERSION et le nouveau EPHEMERAL_MICROVM_IMAGE_VERSION dans .env, puis exécutez docker compose up -d. Les exécutions en cours disposent de cinq minutes au maximum pour se terminer ; celles encore actives après ce délai sont marquées interrupted et ne sont pas relancées : les actions externes ne sont donc jamais répétées. Les migrations de base de données s'exécutent automatiquement.

Sauvegardez à la fois la base de données et la clé maître de chiffrement. Perdre la clé maître rend illisibles les identifiants de connexion et les données d'exécution stockés. L'hôte créé par la pile sauvegarde chaque jour la base de données dans son bucket S3.