Auto-hospedagem

Uma instalação auto-hospedada executa o mecanismo do Ephemeral e o painel de execução em um host que você controla, com workers em microVMs na sua própria conta da AWS e o seu próprio provedor de modelos. Você recebe uma imagem Docker e a sua documentação; a imagem exporta todos os outros arquivos de que você precisa. Ela exige uma licença de implantação do Ephemeral.

O que você executa

O site do cliente, as contas e o faturamento não fazem parte de uma instalação auto-hospedada, nem o código-fonte. As pessoas entram no painel com uma chave de API do mecanismo.

A imagem contém o guia completo do operador. As etapas abaixo o resumem; siga o guia para ver os comandos exatos, a saída esperada, as atualizações, os backups e a solução de problemas:

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

Antes de começar

• Docker com Docker Compose 2.24 ou mais recente, e AWS CLI v2 com o plugin Session Manager.
• Uma conta da AWS em uma região com microVMs do Lambda e permissão para criar uma stack do CloudFormation com funções do IAM.
• Um nome de domínio que você possa apontar para o host.
• Um endpoint de inferência compatível com a OpenAI e a respectiva chave de API.
• Um direito de uso (entitlement) para a sua organização. O Ephemeral o concede após um acordo; veja as licenças de implantação.

Instalar

1. Registre a instalação

   No portal do cliente, abra Implantações e registre esta instalação com um nome, como production-eu. O Ephemeral cria o ID de máquina e o token da licença. Escolha Baixar arquivo da licença para guardar o token, o ID de máquina e o ID da implantação; o token é exibido uma única vez.

2. Baixe a imagem

   Entre no registry com o ID da implantação como nome de usuário e o token da licença como senha e depois baixe uma versão. As versões não têm o 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. Exporte os arquivos da instalação

   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

   Arquivo	Finalidade
   compose.yaml	PostgreSQL, a aplicação e o Caddy, fixados nesta versão
   compose.evaluation.yaml	Override para testar em um computador, sem a AWS
   Caddyfile	Rotas de entrada
   .env	Configuração com segredos recém-gerados. Uma exportação posterior nunca a sobrescreve
   ephemeral-aws.yaml	Template do CloudFormation para os recursos da AWS
   ephemeral-worker-VERSION.zip	O worker compilado que a AWS incorpora à imagem da microVM
   SELF-HOSTING.md	O guia do operador

4. Crie os recursos da AWS

   Envie o ZIP do worker para um bucket S3 privado na sua conta e depois crie a stack. Ela cria uma VPC com uma sub-rede isolada para os workers, um firewall de DNS, a imagem da microVM e o conector de rede, um bucket de armazenamento criptografado, a função do IAM de privilégio mínimo do host e, por padrão, um host Amazon Linux t4g.small com um Elastic IP e um volume de dados criptografado. A criação da imagem do worker leva de 15 a 30 minutos, e a stack cria recursos cobrados.

   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'

   O último comando exibe as configurações da AWS para o mecanismo. Aponte o registro DNS A do seu domínio para a saída da stack HostPublicIp.

5. Configure o host

   Conecte-se com aws ssm start-session --target e a saída da stack HostInstanceId, depois repita o login no registry e a exportação em /srv/ephemeral/install. Edite estas entradas em .env:

   Configuração	Valor
   EPHEMERAL_DOMAIN	Seu hostname, como ephemeral.example.com
   EPHEMERAL_LICENSE_TOKEN	O token da primeira etapa
   EPHEMERAL_MACHINE_ID	O ID de máquina da primeira etapa, exatamente como foi registrado
   INFERENCE_BASE_URL	Seu endpoint compatível com a OpenAI
   INFERENCE_API_KEY	A chave de API dele
   EPHEMERAL_DEFAULT_MODEL	O modelo que as execuções usam quando não indicam nenhum
   Configurações da AWS	As cinco linhas que a stack exibiu: AWS_REGION, EPHEMERAL_S3_BUCKET e três valores EPHEMERAL_MICROVM_…

   A exportação gerou a chave mestra de criptografia, a chave de administrador de bootstrap e a senha do banco de dados. Guarde uma cópia do .env no seu gerenciador de segredos; sem a chave mestra, as credenciais armazenadas e os payloads de execução não podem ser lidos. O instance profile do host fornece as credenciais da AWS.

6. Inicie a instalação

   O Caddy obtém o certificado HTTPS. O PostgreSQL e as APIs internas não são publicados.

   Terminal

   docker compose pull
   docker compose up -d

   O mecanismo valida a licença na inicialização e se recusa a iniciar se ela for inválida ou se a concorrência configurada a exceder.

7. Crie a primeira organização

   Uma instalação nova não tem chaves de API. Execute isto uma vez no diretório da instalação, substituindo my-organization por um ID de organização à sua escolha. O comando lê a chave de bootstrap dentro do contêiner, de modo que a chave não fica no histórico do seu 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

   A resposta contém o id da organização, o key_id e o role da nova chave de proprietário e a própria key, que começa com eph_. Guarde a chave agora; ela não pode ser recuperada depois. Executar o comando de novo para uma organização que tem uma chave ativa retorna 409.

8. Entre

   Abra o seu endereço HTTPS e informe a chave em Chave de API da organização. Crie outras chaves de membro e de administrador em Chaves de API. A chave de administrador de bootstrap do arquivo de configuração apenas cria organizações; ela não pode entrar nem chamar a API.

Teste em um computador

Sem a AWS, adicione o override de avaliação. Os agentes passam a ser executados dentro do contêiner da aplicação com o runner local, e o painel é servido por HTTP simples apenas em http://localhost:8000. Ainda é necessária uma licença; registre uma implantação separada para ela.

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

Diferenças em relação ao serviço hospedado

Atualizações e backups

Para atualizar, envie o ZIP do worker da nova versão e atualize a stack com a chave dele. Depois, no host, exporte os arquivos da nova versão, defina EPHEMERAL_VERSION e o novo EPHEMERAL_MICROVM_IMAGE_VERSION no .env e execute docker compose up -d. As execuções em andamento têm até cinco minutos para terminar; as que ainda estiverem ativas depois disso são marcadas como interrupted e não são reexecutadas, então ações externas nunca se repetem. As migrações do banco de dados são executadas automaticamente.

Faça backup tanto do banco de dados quanto da chave mestra de criptografia. Perder a chave mestra torna ilegíveis as credenciais de conexão e os payloads de execução armazenados. O host criado pela stack faz backup do banco de dados no seu bucket S3 todos os dias.