Autoalojamiento

Una instalación autoalojada ejecuta el motor de Ephemeral y el panel de ejecución en un host que controlas, con workers en microVM de tu propia cuenta de AWS y tu propio proveedor de modelos. Recibes una imagen de Docker y su documentación; la imagen exporta todos los demás archivos que necesitas. Requiere una licencia de despliegue de Ephemeral.

Qué ejecutas

El sitio web de clientes, las cuentas y la facturación no forman parte de una instalación autoalojada, y tampoco el código fuente. Las personas inician sesión en el panel con una clave de API del motor.

La imagen contiene la guía completa del operador. Los pasos siguientes la resumen; sigue la guía para ver los comandos exactos, la salida esperada, las actualizaciones, las copias de seguridad y la resolución de problemas:

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

Antes de empezar

• Docker con Docker Compose 2.24 o posterior, y AWS CLI v2 con el plugin de Session Manager.
• Una cuenta de AWS en una región con microVM de Lambda y permiso para crear una pila de CloudFormation con roles de IAM.
• Un nombre de dominio que puedas apuntar al host.
• Un endpoint de inferencia compatible con OpenAI y su clave de API.
• Un derecho de uso para tu organización. Ephemeral lo concede tras un acuerdo; consulta licencias de despliegue.

Instalar

1. Registra la instalación

   En el portal de clientes, abre Despliegues y registra esta instalación con un nombre, como production-eu. Ephemeral crea su ID de máquina y su token de licencia. Elige Descargar archivo de licencia para guardar el token, el ID de máquina y el ID del despliegue; el token se muestra una sola vez.

2. Descarga la imagen

   Inicia sesión en el registro con el ID del despliegue como nombre de usuario y el token de licencia como contraseña, y luego descarga una versión. Las versiones no llevan una v inicial.

   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. Exporta los archivos de instalación

   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

   Archivo	Finalidad
   compose.yaml	PostgreSQL, la aplicación y Caddy, fijados a esta versión
   compose.evaluation.yaml	Sobrescritura para probarlo en un solo equipo sin AWS
   Caddyfile	Rutas de entrada
   .env	Configuración con secretos recién generados. Una exportación posterior nunca la sobrescribe
   ephemeral-aws.yaml	Plantilla de CloudFormation para los recursos de AWS
   ephemeral-worker-VERSION.zip	El worker compilado que AWS incorpora a la imagen de microVM
   SELF-HOSTING.md	La guía del operador

4. Crea los recursos de AWS

   Sube el ZIP del worker a un bucket de S3 privado de tu cuenta y luego crea la pila. Crea una VPC con una subred aislada para los workers, un firewall de DNS, la imagen de microVM y el conector de red, un bucket de almacenamiento cifrado, el rol de IAM de mínimos privilegios del host y, por defecto, un host Amazon Linux t4g.small con una Elastic IP y un volumen de datos cifrado. Compilar la imagen del worker tarda entre 15 y 30 minutos, y la pila crea recursos 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'

   El último comando imprime los ajustes de AWS para el motor. Apunta el registro DNS A de tu dominio a la salida de la pila HostPublicIp.

5. Configura el host

   Conéctate con aws ssm start-session --target y la salida de la pila HostInstanceId, y repite el inicio de sesión en el registro y la exportación en /srv/ephemeral/install. Edita estas entradas en .env:

   Ajuste	Valor
   EPHEMERAL_DOMAIN	Tu nombre de host, como ephemeral.example.com
   EPHEMERAL_LICENSE_TOKEN	El token del primer paso
   EPHEMERAL_MACHINE_ID	El ID de máquina del primer paso, exactamente como se registró
   INFERENCE_BASE_URL	Tu endpoint compatible con OpenAI
   INFERENCE_API_KEY	Su clave de API
   EPHEMERAL_DEFAULT_MODEL	El modelo que usan las ejecuciones cuando no indican ninguno
   Ajustes de AWS	Las cinco líneas que imprimió la pila: AWS_REGION, EPHEMERAL_S3_BUCKET y tres valores EPHEMERAL_MICROVM_…

   La exportación generó la clave maestra de cifrado, la clave de administrador de arranque y la contraseña de la base de datos. Guarda una copia de .env en tu gestor de secretos; sin la clave maestra, las credenciales y los datos de las ejecuciones almacenados no se pueden leer. El perfil de instancia del host proporciona las credenciales de AWS.

6. Inicia la instalación

   Caddy obtiene el certificado HTTPS. PostgreSQL y las API internas no se publican.

   Terminal

   docker compose pull
   docker compose up -d

   El motor valida la licencia al arrancar y se niega a iniciarse si no es válida o si la concurrencia configurada la supera.

7. Crea la primera organización

   Una instalación nueva no tiene claves de API. Ejecuta esto una vez en el directorio de la instalación, sustituyendo my-organization por el ID de organización que prefieras. Lee la clave de arranque dentro del contenedor, así que la clave no queda en el historial de tu 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 respuesta contiene el id de la organización, el key_id y el role de la nueva clave de propietario, y la propia key, que empieza por eph_. Guarda la clave ahora; no se puede recuperar después. Ejecutar de nuevo el comando para una organización que tiene una clave activa devuelve 409.

8. Inicia sesión

   Abre tu dirección HTTPS e introduce la clave en Clave de API del motor. Crea más claves de miembro y de administrador en Claves de API. La clave de administrador de arranque del archivo de configuración solo crea organizaciones; no puede iniciar sesión ni llamar a la API.

Pruébalo en un solo equipo

Sin AWS, añade la sobrescritura de evaluación. Los agentes se ejecutan entonces dentro del contenedor de la aplicación con el ejecutor local, y el panel se sirve por HTTP sin cifrar solo en http://localhost:8000. Sigue siendo necesaria una licencia; registra un despliegue aparte para ello.

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

Diferencias con el servicio alojado

Actualizaciones y copias de seguridad

Para actualizar, sube el ZIP del worker de la nueva versión y actualiza la pila con su clave. Después, en el host, exporta los archivos de la nueva versión, establece EPHEMERAL_VERSION y el nuevo EPHEMERAL_MICROVM_IMAGE_VERSION en .env, y ejecuta docker compose up -d. Las ejecuciones en curso disponen de hasta cinco minutos para terminar; las que sigan activas después se marcan como interrupted y no se reintentan, así que las acciones externas nunca se repiten. Las migraciones de la base de datos se ejecutan automáticamente.

Haz copia de seguridad tanto de la base de datos como de la clave maestra de cifrado. Perder la clave maestra deja ilegibles las credenciales de conexión y los datos de las ejecuciones almacenados. El host creado por la pila copia la base de datos a su bucket de S3 cada día.