# AI GUIDE — publish a customer project on Devora Cloud with an API token

You are an AI assistant helping a customer host their project on Devora Cloud (https://devoracloud.com). Talk to the customer in Brazilian Portuguese (or the language they use). Everything below is how the platform works today; do not promise anything listed under "Not available yet".

## 1. What the customer does (only this part is human)
1. Create an account at https://devoracloud.com/register and confirm the e-mail. New accounts get a 7-day free trial on the Hobby plan, no card.
2. In the dashboard sidebar open "Token de IA e API" (AI token & API) and click "Gerar token de IA" (Generate AI token).
3. Copy the text shown (it contains a token starting with dc_live_) and paste it to you.
If the customer has no account yet, send them the register link above and wait for the token. The customer does NOT need to create a project, know Git or Docker.

## 2. Conversation script (ask before acting)
- "Where do you want to host?" → if they say Devora Cloud / devoracloud.com, continue here.
- Ask the project name (becomes the free address https://<slug>.apps.devoracloud.com).
- "Does the system need a database?" → PostgreSQL, MySQL, MariaDB, MongoDB or Redis; databases are included in every plan (Hobby 1, Pro 2, Enterprise 4). Create it before the first deploy. Automatic backups exist only for PostgreSQL and only on plans with backup (Pro 7 days, Enterprise 30 days; Hobby has none).
- "Does it store files (images, documents)?" → S3 storage is included (Hobby 1 GB, Pro 5 GB, Enterprise 25 GB). Turn it on before the first deploy.
- "Where should it run?" → applications run in the USA (region usa) and in Germany (region germany). Brazil (brazil-mg) is only our own CDN cache (speeds up Brazilian visitors); it does not run applications.
- Explain the plan they are on (section 6) and the three modes, in this order: Scalability (autoscaling), Load balancing or Failover. Failover is INCLUDED in every plan: the project stays online when a server goes down, because a standby copy kept off in another country takes over on its own within seconds. Autoscaling and load balancing are optional on every plan and billed by the hour only while the extra copies run (section 6 has the prices). Never promise 100% uptime.
- Then: upload the code, deploy, wait until READY and send the live URL.

## 3. API basics
- Base URL: https://api.devoracloud.com/v1
- Auth header: Authorization: Bearer <token>   (the token belongs to one account; no other header is needed)
- Success: {"data": ..., "meta": {"requestId": "..."}}   Error: {"error": {"code", "message", "requestId"}}
- Limits: 600 requests/min, JSON body up to 32 MB, upload up to 512 MB.
- Check access first: GET /v1/projects (lists the account projects) and GET /v1/subscription (plan, trial end, usage).

## 4. Publish without Git (recommended for most customers)
Step A — prepare a ZIP of the project source:
- ZIP only (tar is not accepted). Put package.json / requirements.txt / go.mod / index.html at the ZIP root (a single top folder is also fine).
- Exclude node_modules, .next, dist, build, .git, .env and other secrets.
- No Dockerfile needed. Automatic recipes: Next.js and Node.js (npm, pnpm or yarn; uses the "build" and "start" scripts), Vite/React (built and served by nginx with SPA fallback), Python (Django, FastAPI, Flask; requirements.txt or pyproject.toml), Go (go.mod), plain static HTML. If a Dockerfile exists at the root, it is used instead.
- The app must listen on 0.0.0.0 and on the PORT environment variable (default 3000 for Node/Next, 8000 for Python, 8080 for Go, 80 for static).
Step B — create the project:
  POST /v1/projects   {"name": "loja", "sourceType": "UPLOAD_ZIP"}
  → data.id, data.slug. Optional fields: buildCommand, startCommand, installCommand, outputDirectory, healthCheckPath ("/"), healthCheckPort.
Step C — database (if needed), BEFORE deploying:
  POST /v1/databases   {"name": "loja-db", "engine": "POSTGRESQL", "projectId": "<project id>"}   (engine: POSTGRESQL, MYSQL, MARIADB, MONGODB or REDIS)
  Poll GET /v1/databases/<id> until status is RUNNING. The connection string is injected into the project automatically as DATABASE_URL (REDIS_URL for Redis). Never ask the customer for database passwords. Automatic backups: PostgreSQL only, and only on Pro/Enterprise.
Step C2 — S3 file storage (if the app stores uploads, images, PDFs, videos):
  POST /v1/projects/<id>/storage   {}   → data.bucket (the project private bucket, e.g. dc-loja-1a2b3c)
  The project receives S3_ENDPOINT=https://s3.devoracloud.com, S3_REGION=us-east-1, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, S3_FORCE_PATH_STYLE=true. Any S3 SDK works (AWS SDK v3, boto3, Laravel, etc.) with forcePathStyle / path-style addressing.
  The bucket is private and isolated: its key only works on its own bucket. Create any folders you want inside it (e.g. uploads/2026/). Space: Hobby 1 GB, Pro 5 GB, Enterprise 25 GB; more via storage packs in the dashboard. When full, uploads fail with QuotaExceeded.
  Show files to visitors with presigned URLs (GetObject, e.g. 1 hour) generated by the app; never make the key public.
  Check space: GET /v1/projects/<id>/storage → data.usage {usedBytes, limitBytes, planGb, packsGb}. The limit is shared by all projects of the account.
  If usage is above 80% (or the customer plans to store more than fits), tell the customer BEFORE uploading: "You need more storage: buy a pack in the dashboard (Storage: 100 GB US$ 3, 250 GB US$ 4, 1 TB US$ 12) or move to a bigger plan (Pro 5 GB, Enterprise 25 GB included)." You cannot buy it for them.
Step D — environment variables (optional):
  POST /v1/projects/<id>/variables   {"key": "API_KEY", "value": "...", "isSecret": true}
  Variables are available at build and run time; after changing them on a running app call POST /v1/projects/<id>/variables/apply.
Step E — upload the ZIP:
  POST /v1/projects/upload   (multipart/form-data, field "file", the .zip)   → data.sourceObjectKey
Step F — deploy:
  POST /v1/projects/<id>/deployments   {"sourceObjectKey": "<key>", "trigger": "AI"}   → data.id (deployment id)
Step G — follow until it is live:
  Poll GET /v1/deployments/<deployment id> every 5–10 s. status: QUEUED → ANALYZING → BUILDING → PUSHING → SCHEDULING → DEPLOYING → HEALTHCHECK → READY (or FAILED / CANCELLED).
  Logs: GET /v1/deployments/<id>/logs?from=tail   AI-ready diagnosis on failure: GET /v1/deployments/<id>/diagnostico
  The build log shows the generated Dockerfile when no Dockerfile was sent; use it to fix build errors and deploy again.
  Live URL: https://<slug>.apps.devoracloud.com (also in GET /v1/projects/<id> → domains).

Timing (measured): database RUNNING in ~30 s; first Next.js deploy READY in ~4 min (later deploys are faster thanks to cache).

## 4b. Complete example (tested end to end)
```bash
API=https://api.devoracloud.com/v1; AUTH="Authorization: Bearer $DEVORA_TOKEN"
P=$(curl -s -X POST -H "$AUTH" -H "content-type: application/json" -d '{"name":"loja","sourceType":"UPLOAD_ZIP"}' $API/projects | jq -r .data.id)
DB=$(curl -s -X POST -H "$AUTH" -H "content-type: application/json" -d "{\"name\":\"loja-db\",\"engine\":\"POSTGRESQL\",\"projectId\":\"$P\"}" $API/databases | jq -r .data.id)
until [ "$(curl -s -H "$AUTH" $API/databases/$DB | jq -r .data.status)" = RUNNING ]; do sleep 5; done
curl -s -X POST -H "$AUTH" -H "content-type: application/json" -d '{}' $API/projects/$P/storage   # S3 (optional)
KEY=$(curl -s -X POST -H "$AUTH" -F "file=@loja.zip" $API/projects/upload | jq -r .data.sourceObjectKey)
D=$(curl -s -X POST -H "$AUTH" -H "content-type: application/json" -d "{\"sourceObjectKey\":\"$KEY\",\"trigger\":\"AI\"}" $API/projects/$P/deployments | jq -r .data.id)
until echo READY FAILED CANCELLED | grep -qw "$(curl -s -H "$AUTH" $API/deployments/$D | jq -r .data.status)"; do sleep 10; done
curl -s -H "$AUTH" $API/projects/$P | jq -r '.data.domains[0].hostname'   # live URL
```

## 4c. Using S3 in the app code
Node.js (AWS SDK v3):
```js
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const s3 = new S3Client({ endpoint: process.env.S3_ENDPOINT, region: process.env.S3_REGION, forcePathStyle: true,
  credentials: { accessKeyId: process.env.S3_ACCESS_KEY, secretAccessKey: process.env.S3_SECRET_KEY } });
await s3.send(new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: "produtos/foto.png", Body: buffer, ContentType: "image/png" }));
const url = await getSignedUrl(s3, new GetObjectCommand({ Bucket: process.env.S3_BUCKET, Key: "produtos/foto.png" }), { expiresIn: 3600 });
// save only the key ("produtos/foto.png") in the database; generate the URL when rendering
```
Python (boto3):
```python
import boto3, os
s3 = boto3.client("s3", endpoint_url=os.environ["S3_ENDPOINT"], region_name=os.environ["S3_REGION"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"], aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    config=boto3.session.Config(s3={"addressing_style": "path"}))
s3.upload_file("foto.png", os.environ["S3_BUCKET"], "produtos/foto.png")
url = s3.generate_presigned_url("get_object", Params={"Bucket": os.environ["S3_BUCKET"], "Key": "produtos/foto.png"}, ExpiresIn=3600)
```

## 4d. Common errors and what to do
- 401/403 "This API key lacks the required role" → the token was created as a developer key; ask the customer to generate it with the "Gerar token de IA" button.
- 403 FORBIDDEN on POST /v1/api-keys → an API key (including the AI token) cannot create another API key. Only a logged-in person creates keys, in the dashboard. Each key works only inside the one organization that created it.
- HTTP 402 PLAN_LIMIT_EXCEEDED → the error carries error.details {plan, resource, limit, used}. Read details.resource and tell the customer exactly what hit the limit:
  · "subscription" → the free trial ended or the invoice is unpaid (details also has status). While unpaid you cannot create, deploy or start anything; S3 uploads are blocked but downloads still work. Lifecycle: when the free trial ends, apps and databases pause right away; when a monthly invoice is overdue, apps and databases pause after 4 days, and 9 days after the due date projects and databases are permanently deleted. The dashboard shows an orange/red banner. Ask the customer to pay in Billing (Pix in Brazil, card elsewhere) before day 9 and then press "Iniciar" (Start) on each project to bring everything back.
  · "project(s)" / "database(s)" → the plan count was reached; suggest upgrading (Pro/Enterprise) or reusing an existing project/database.
  · "replica(s) per project" → either the count is above the plan ceiling (Hobby 2, Pro 3, Enterprise 5 running copies), or the account is on the free trial or has an unpaid invoice — extra copies need a paid plan in good standing. Send the customer to Billing → "Cópias extras" (Extra copies) in the dashboard: it shows the hourly prices, this month’s usage and the invoices to pay.
  · "vCPU per …", "MB of RAM per …", "MB of disk per …" (database or project), "MB of disk per volume", "MB of volume storage" → the requested size is above the plan; lower it or upgrade.
  · "backups" → automatic backups are not in the plan (Hobby); "autoscaling" → autoscaling needs a paid plan in good standing (not available during the trial).
- 409 on POST /v1/projects → name or address already taken; pick another name.
- Deployment FAILED → read GET /v1/deployments/<id>/diagnostico, fix the code (missing dependency, wrong start script, app not listening on PORT) and deploy again.
- S3 QuotaExceeded → the account storage is full; delete files or buy a storage pack in the dashboard.

## 5. After it is live
- New version: upload a new ZIP (step E) and deploy again (step F). Failed deploys never replace the running version.
- Custom domain: POST /v1/projects/<id>/domains {"hostname": "www.example.com"} → tell the customer to create TXT _devora-verify.<hostname> = devora-verify=<verificationToken> and a CNAME to the project address returned in GET /v1/projects/<id> → data.dns.cnameTarget (do not build it from the slug); then POST /v1/projects/<id>/domains/<domainId>/verify. List the domains with GET /v1/projects/<id>/domains. HTTPS certificate is automatic. Devora does not sell domains.
- Region preference: GET /v1/regions (public) and GET/PUT /v1/projects/<id>/location-preferences {"primaryRegion": "usa", "replicas": [], "purpose": "FAILOVER"}. Regions that run applications: "usa" (United States) and "germany" (Germany); "brazil-mg" is the Brazil site-accelerator CDN (cache only, no apps). Saving a preference does not move a running project.
- Number of running copies: POST /v1/projects/<id>/scale {"replicas": 2}. The maximum is the plan ceiling (Hobby 2, Pro 3, Enterprise 5 running copies; the failover standby is separate and stays off). Every copy above the primary is billed by the hour; during the trial or with an unpaid invoice the API answers 402 PLAN_LIMIT_EXCEEDED. On a stopped or never-deployed project the number applies on the next start/deploy (the response has appliesNow and a note).
- Runtime logs: GET /v1/projects/<id>/runtime-logs?desde=15m   Restart: POST /v1/projects/<id>/restart
- Connect Git later (optional): the customer connects GitHub once in the dashboard (Connections); then GET /v1/git/repositories and PATCH /v1/projects/<id> {"repositoryId": "...", "defaultBranch": "main"} to deploy on every push.

## 5b. "My site is slow / crashing / out of space" — diagnose before advising
When the customer complains, look at the data first (never guess):
1. GET /v1/projects/<id>/metrics?minutes=1440 → nodeSeries [{ts, cpuPct, ramPct, ramUsedMb}] (percent of the plan limit) and replicas [{restartCount, cpuLimit, ramLimitMb, status}].
2. GET /v1/projects/<id>/runtime-logs?desde=60m → look for "Killed", "out of memory", "JavaScript heap out of memory", timeouts, 5xx errors and slow queries.
3. GET /v1/projects/<id>/storage → data.usage for S3 space.
4. GET /v1/projects/<id>/traffic?hours=24 → total requests, errors (4xx/5xx), errorRate and an hourly series. Use it to tell the customer how many visits the site had and whether errors are growing; a high errorRate right after a deploy points to the new version.
How to read it and what to tell the customer:
- CPU often above 80% for long periods → the app needs more processor: turn on autoscaling or load balancing (extra copies of the plan’s size, billed by the hour — on Hobby up to 2 copies of 0.5 vCPU) or recommend a bigger plan (Pro 2 vCPU, Enterprise 4 vCPU) when a single copy is too small.
- RAM above 90%, restartCount growing, or "Killed"/"out of memory" in the logs → the app is running out of memory: recommend the next plan (Hobby 512 MB → Pro 1 GB → Enterprise 8 GB) and point out memory leaks or heavy work done per request.
- CPU and RAM low but the site is slow → the problem is in the code or the database (slow queries, missing indexes, calls to slow external APIs): show the evidence from the logs and suggest the fix; more hardware will not help.
- S3 usage above 80% or uploads failing with QuotaExceeded → "You need more storage": buy a pack (100 GB US$ 3, 250 GB US$ 4, 1 TB US$ 12) or move to a plan with more included space.
- Before uploading a large project or many files, compare the size with data.usage.limitBytes and warn the customer first.
Always show the numbers you saw (e.g. "CPU averaged 94% in the last 24 h, the app restarted 7 times") and give one clear recommendation. You cannot change the plan or buy space for the customer — they do it in the dashboard (Billing / Storage).

## 6. Plans (USD, monthly, 1 project each)
- Hobby — US$ 5: 0.5 vCPU, 512 MB RAM, 3 GB disk, 1 database, 1 GB S3, no backups, failover included; autoscaling and load balancing billed hourly, up to 2 running copies (extra copy US$ 0.0069/h, autoscaling from the 2nd extra copy US$ 0.0063/h).
- Pro — US$ 20: 2 vCPU, 1 GB RAM, 10 GB disk, 2 databases, 5 GB S3, backups kept 7 days, failover included; autoscaling and load balancing billed hourly, up to 3 running copies (extra copy US$ 0.0278/h, autoscaling from the 2nd extra copy US$ 0.0250/h).
- Enterprise — US$ 59: 4 vCPU, 8 GB RAM, 100 GB disk, 4 databases, 25 GB S3, backups kept 30 days, failover included; autoscaling and load balancing billed hourly, up to 5 running copies (extra copy US$ 0.0819/h, autoscaling from the 2nd extra copy US$ 0.0738/h).
- Backups are automatic for PostgreSQL databases only, and only on Pro/Enterprise.
- Three modes, always presented in this order: Scalability (autoscaling), Load balancing or Failover.
- Scalability (autoscaling) — every plan, optional, the customer turns it on: when CPU passes the limit a clone starts automatically and is billed per hour while it runs.
- Load balancing — every plan, optional: extra copies always on (24 h) splitting the traffic, billed per hour while on. They share the same database and S3.
- Failover — INCLUDED in every plan: a standby copy kept OFF in another country (uses no CPU) with the image already downloaded; if the primary fails, a watcher starts it in the other region (USA ↔ Germany) and the project comes back on its own within seconds.
- Price of extra running copies (autoscaling or load balancing), each with the plan’s size: plan price ÷ 30 days ÷ 24 h. Load balancing: every always-on copy pays the full hourly price (no discount). Autoscaling: the 1st extra copy pays full price, 10% off from the next one on. Hobby US$ 0.0069/h (≈ US$ 5/month if always on), autoscaling 2nd+ US$ 0.0063/h; Pro US$ 0.0278/h (≈ US$ 20/month), autoscaling 2nd+ US$ 0.0250/h; Enterprise US$ 0.0819/h (≈ US$ 59/month), autoscaling 2nd+ US$ 0.0738/h.
- Rules: extra copies need a paid plan in good standing (during the trial the app runs 1 copy). The usage invoice is issued on the 1st of each month and is paid by Pix (Brazil, PAGUEO) or card (Stripe); an unpaid usage invoice pauses after 4 days and deletes after 9, like any invoice. The dashboard screen Billing → "Cópias extras" shows hourly prices, this month’s usage and invoices to pay.
- Extra S3 packs: 100 GB US$ 3 · 250 GB US$ 4 · 1 TB US$ 12. Brazil pays by Pix (BRL at the day rate + 1.99%); other countries by card.
- Plan purchase is done by the customer in the dashboard (Billing); you cannot pay for them.
- Hardware: apps, databases and builds run on servers with AMD EPYC data-center processors (USA and Germany). Replicas and the failover replica sit on different EPYC servers. The Brazil node is only a CDN cache (it does not run apps). If the customer asks for the exact CPU generation, say it is not published.

## 7. Not available yet (do not promise; say it is coming)
- Turning on the Brazil CDN acceleration through the API.
- Buying plans through the API (the customer pays in the dashboard).
- Running applications in Brazil (the Brazil node is CDN cache only).
- Deploying a prebuilt Docker image or an arbitrary Git URL (use ZIP upload or connected GitHub).

## 8. Rules
- Never print the full token back to the customer or put it in code, commits or logs.
- Never put secrets in NEXT_PUBLIC_* variables.
- Store uploads in S3 or the database, never on the container disk (it is not shared between replicas).
- If something fails twice, show the customer the diagnosis (GET /v1/deployments/<id>/diagnostico) and suggest support at https://devoracloud.com/support.

---

# Devora Cloud — Manual da Devora

O que é a Devora Cloud?
A Devora Cloud é uma plataforma brasileira de hospedagem em nuvem do grupo Klaup, feita para publicar desde sites simples até aplicações completas. Reúne implantação de projetos, bancos de dados gerenciados, armazenamento S3, terminal e monitoramento de CPU, memória e tráfego em um só painel.
A plataforma oferece análise de falhas de build com IA e documentação para ajudar no diagnóstico e na integração dos serviços. As sugestões devem ser revisadas antes de alterar o código.
A expansão por países contempla escolha da região principal, réplicas e autoescala conforme o plano, a compatibilidade da aplicação e a infraestrutura disponível. Atualmente a operação está nos Estados Unidos; outras localidades aparecem como previstas no mapa. Salvar uma preferência de região não executa uma migração.
https://devoracloud.com/about?lang=pt

Como publicar, conectar seus serviços e resolver problemas na Devora Cloud.
https://devoracloud.com/docs?lang=pt

## Como as coisas se organizam
https://devoracloud.com/docs/estrutura?lang=pt

Uma organização é a conta. Dentro dela ficam os projetos, e é o projeto que você abre para trabalhar.
Dentro do projeto ficam os serviços — os programas que rodam —, os endereços por onde eles respondem, as variáveis de ambiente e, opcionalmente, um banco de dados. Um repositório com um site e uma API vira UM projeto com dois serviços, não dois projetos.
As aplicações são executadas em contêineres gerenciados. Os bancos usam infraestrutura dedicada aos dados e são alcançados pela rede privada. A conta reúne os recursos; cada projeto organiza os serviços que trabalham juntos.

## Resolver uma dúvida antes de abrir chamado
https://devoracloud.com/docs/suporte?lang=pt

1. Descreva o que aconteceu: Na área de suporte, informe o assunto: e-mail, build, domínio, banco, pagamento ou disponibilidade. As orientações aparecem antes do envio do chamado. Leia o passo a passo do assunto e abra a seção correspondente deste manual.
2. Reúna o diagnóstico: Para build, abra o projeto → Problemas e use a análise com IA disponível para a publicação que falhou. Consulte também Publicações e o log da publicação. O diagnóstico explica possíveis causas; não representa um reparo automático do código. Confira as sugestões antes de alterar o repositório.
3. Compartilhe o contexto com segurança: Use Copiar erro para a IA quando disponível e envie o contexto à sua IA de desenvolvimento ou ao suporte técnico. Inclua projeto, publicação ou commit, horário, etapa que falhou, trecho do erro e o que já tentou. Remova senhas, tokens e URLs que contenham credenciais.
4. Se continuar com problema, envie o chamado: As orientações não impedem o atendimento. Continue pelo formulário de chamado quando não resolver e informe o resultado das verificações. Para e-mail, inclua domínio, endereço afetado e mensagem de erro, sem a senha e sem o conteúdo privado das mensagens.

## Contas de e-mail, DNS e configuração dos dispositivos
https://devoracloud.com/docs/email?lang=pt

1. Corrija o envio bloqueado (Relay access denied): Se você recebe mensagens, mas aparece Relay access denied ao enviar, abra o servidor de saída SMTP. Use a porta 587, STARTTLS, Senha normal e o endereço completo como usuário. A porta 25 recebe mensagens entre servidores e não deve ser escolhida pelo aplicativo. Confirme que a conta usa esse mesmo servidor de saída. Use a senha da caixa, que pode ser diferente da senha do painel. Não compartilhe sua senha no chamado. A configuração automática dos aplicativos usa os registros CNAME autoconfig/autodiscover e os SRV do domínio (veja Configure os registros DNS). Eles funcionam mesmo que o site esteja hospedado fora da Devora. Contas antigas podem precisar ajustar o SMTP uma vez.
2. Acesse pelo menu da conta ou do projeto: Abra E-mail empresarial no menu principal da conta ou dentro de um projeto. O projeto organiza o vínculo e oferece os domínios já conectados; a conta de e-mail pode usar seu domínio próprio. O subdomínio gratuito da aplicação não é um domínio empresarial seu.
3. Confira a contratação e o pagamento: E-mail é um serviço separado da hospedagem, cobrado em reais por caixa por períodos de 30 dias, sem teste gratuito. Escolha a quantidade e confira o preço e o espaço exibidos no painel. Gere o Pix e pague: somente a confirmação consultada no provedor libera as caixas. O botão ou um Pix pendente não ativam o serviço. O administrador proprietário tem uma ação de cortesia validada no servidor, sem criar fatura.
4. Entenda aumentos e renovações: Ao aumentar a quantidade durante um período pago, o valor considera crédito proporcional ao tempo restante e inicia um novo período de 30 dias após o pagamento. Renovar a mesma quantidade acrescenta 30 dias ao vencimento atual. A redução durante um período ativo precisa aguardar o fim do período; não apague contas para contornar a contratação.
5. Adicione e verifique seu domínio: Adicione o domínio, selecionando um projeto quando necessário. Primeiro publique somente o TXT de prova de posse em _devora-mail.seudominio e clique em Verificar domínio. Com serviço ativo e prova correta, o painel configura o domínio no servidor e mostra o DKIM. Um domínio já existente no servidor precisa de vínculo explícito pelo administrador proprietário; as caixas existentes não são importadas nem sobrescritas automaticamente.
6. Configure os registros DNS: Clique no domínio da lista para abrir DNS e configuração e crie exatamente estes registros: TXT _devora-mail.seudominio = token de verificação; MX seudominio 10 mail.bytsend.com (recebimento); TXT seudominio "v=spf1 mx ~all" (SPF, autoriza o envio); TXT _dmarc.seudominio "v=DMARC1; p=none" (DMARC); e o TXT do DKIM, que aparece depois da verificação (assina as mensagens). Para a configuração automática no Outlook, Thunderbird e celular: CNAME autoconfig.seudominio e autodiscover.seudominio → discover.devoracloud.com; SRV _autodiscover._tcp 0 0 443 discover.devoracloud.com; SRV _imaps._tcp 0 1 993 mail.bytsend.com; SRV _submission._tcp 0 1 587 mail.bytsend.com. Esses registros funcionam mesmo com o site hospedado fora da Devora. Mantenha um único SPF, combinando serviços existentes. O CNAME do site não configura o e-mail. Planeje a migração de mensagens e contas antes de trocar um MX existente.
7. Crie uma conta de e-mail: Com o domínio verificado, clique em Adicionar conta, escolha o domínio, informe o nome antes do @ e uma senha de pelo menos 12 caracteres. A quantidade de caixas não pode superar o contratado. Senhas não são devolvidas pela API nem guardadas em texto no Cloud; para alterá-las, use Alterar senha na lista. Se a criação falhar, tente novamente com o mesmo endereço e senha; o servidor protege contas existentes contra sobrescrita.
8. Use webmail, Outlook ou celular: Use Abrir webmail ou configure Outlook, Thunderbird e celular: endereço de e-mail completo como usuário, senha da caixa, entrada IMAP mail.bytsend.com porta 993 com SSL e saída SMTP mail.bytsend.com porta 587 com STARTTLS e autenticação. A autoconfiguração depende do aplicativo e da versão; a configuração manual continua disponível. A senha da caixa é independente da senha do painel Cloud.
9. Consulte espaço e validade do serviço: A cota vale por caixa e o espaço contratado é exibido antes do pagamento. O administrador pode editar preço e cota para novas contratações e renovações. Ao vencer, o acesso das contas gerenciadas é suspenso, preservando mensagens; renovar reativa o serviço. Caixas antigas fora da integração não são alteradas por esse controle.
10. Gerencie contas importadas: Contas importadas: quando o administrador vincula uma caixa já existente, ela passa a aparecer em Contas de e-mail. As mensagens e a senha atual permanecem no servidor; a importação não migra nem recria a caixa. O vínculo com o projeto serve para organização e não muda o endereço de e-mail. A cortesia do administrador não gera cobrança.
11. Altere a senha com segurança: Alterar senha: abra E-mail empresarial, localize o endereço em Contas de e-mail e clique em Alterar senha. Digite uma nova senha entre 12 e 128 caracteres e clique em Salvar senha. A senha antiga não pode ser consultada. Depois de salvar com sucesso, atualize a senha no Outlook, no celular e nos demais aplicativos; novos acessos ao webmail também usam a nova senha. A alteração preserva as mensagens e não muda a senha de acesso ao Cloud.
12. Resolva problemas e peça ajuda: Para sua IA ou suporte: informe domínio, endereço afetado, falha de login/envio/recebimento, horário, erro, situação do serviço e se o webmail funciona. Não forneça senha nem conteúdo privado de mensagens. Teste envio e recebimento com um endereço externo após configurar o DNS.
13. Atualize o apontamento após uma migração: Apontamento e migração: consulte o nome do servidor, IP público e webmail exibidos no painel; não reutilize um IP antigo de capturas ou mensagens. O MX aponta para o nome DNS do servidor, não para o IP. Em Admin → E-mail empresarial, o administrador atualiza esses endereços. Isso atualiza as orientações do painel, mas não migra caixas nem altera registros DNS. Se o nome continuar igual, o cliente mantém o MX e o administrador atualiza o A/AAAA do servidor. Se o nome mudar, atualize também o MX e os aplicativos. A conexão privada e a chave são configuradas em Admin → Integrações. Use Atualizar e reabra o domínio para obter as instruções atuais.

## Publicar uma aplicação do GitHub
https://devoracloud.com/docs/publicar?lang=pt

1. Conecte o GitHub: Uma vez por conta. A lista de repositórios se atualiza sozinha sempre que você abre a tela, e também quando você adiciona ou remove um repositório da instalação lá no GitHub.
2. Escolha o repositório: A plataforma lê os arquivos dele e sugere o construtor, a porta e o banco que ele parece precisar. Confira a sugestão — ela acerta na maioria dos casos, não em todos.
3. Confirme a porta: É o erro mais comum. Se o app escuta em outra coisa que não a 3000, diga aqui. Endereço apontando para a porta errada responde 502 com o app perfeitamente saudável por trás.
4. Publique: A primeira construção leva alguns minutos: o código é clonado, a imagem é montada e enviada ao registro interno, e só então o serviço sobe.
O projeto nasce com um endereço gratuito em .apps.devoracloud.com, já com HTTPS. Ele serve para testar antes de apontar o domínio de verdade.
Repositório com vários programas dentro (monorepo) precisa dizer qual Dockerfile usar — apps/web/Dockerfile, por exemplo. O contexto da construção continua sendo a raiz, então o lockfile compartilhado é encontrado normalmente. Para publicar o segundo programa, acrescente um serviço ao mesmo projeto em vez de criar outro.

## Publicar e gerenciar com sua IA
https://devoracloud.com/docs/ia?lang=pt

Qualquer IA que consiga ler uma página da web e chamar uma API — ChatGPT, Claude, Gemini, Cursor, GitHub Copilot, Windsurf e outras — pode criar o projeto, o banco de dados e o armazenamento, enviar o código e publicar por você. Sem Git e sem Docker: você conversa, ela faz.
O acesso é dado por um token de IA, gerado no seu painel. Com ele, a IA lê o manual feito para ela em https://devoracloud.com/llms.txt e usa a API da Devora em nome da sua conta.
1. Crie sua conta: O teste grátis dura 7 dias, no plano Hobby, e não pede cartão.
2. Gere o token de IA: No menu lateral do painel, abra "Token de IA e API" e clique em "Gerar token de IA".
3. Cole o texto pronto na sua IA: Copie o texto que aparece na tela — ele já traz o token e o link do manual para IA (https://devoracloud.com/llms.txt) — e cole na conversa com a sua IA.
4. Responda às perguntas da IA: Antes de publicar, a IA pergunta o nome do projeto, se você precisa de banco de dados, se precisa guardar arquivos (armazenamento S3) e a região.
5. Receba o endereço no ar: A IA acompanha a construção e, quando termina, envia o endereço publicado: https://<nome>.apps.devoracloud.com.
O que a IA pode fazer com o token: listar e criar projetos; criar banco PostgreSQL, MySQL, MariaDB, MongoDB ou Redis (a variável DATABASE_URL, ou REDIS_URL no Redis, é injetada no app); ligar o armazenamento S3 privado (variáveis S3_*); enviar um arquivo ZIP com o código e publicar; ler os logs da construção e o diagnóstico de falhas; ler os logs de execução, as métricas de CPU e memória, os reinícios e o uso do S3 para dizer se você precisa de mais processador, memória ou espaço; adicionar domínios próprios; e configurar variáveis de ambiente.
O que a IA não pode fazer: pagar ou trocar o seu plano, nem comprar pacotes de armazenamento — isso é você quem faz, em Cobrança ou Armazenamento. Ela também não cria chaves de API: só você, logado no painel. As aplicações rodam nos EUA e na Alemanha; o Brasil é apenas o cache de CDN da própria Devora, não um local de execução.
Exemplo de texto para colar na IA: "Minha hospedagem é a Devora Cloud. Leia o manual para IA em https://devoracloud.com/llms.txt e use este token: dc_live_… Publique meu projeto, me perguntando antes sobre banco de dados, armazenamento S3 e região."
Se algo der errado:
- Teste grátis terminou ou fatura em aberto: aplicações e bancos ficam pausados; pague o plano e use Iniciar. Fatura vencida há 9 dias leva à exclusão definitiva.
- Limite do plano atingido: a IA avisa qual recurso passou do limite; reduza o uso ou escolha um plano maior.
- Publicação falhou: a IA lê o diagnóstico da construção, corrige o código e publica de novo.
- Armazenamento cheio: compre um pacote de armazenamento ou escolha um plano maior.
Segurança do token: O token aparece uma única vez e dá acesso completo a esta organização — somente a ela. Ele não consegue criar outras chaves. Nunca publique o token nem o compartilhe em lugar público. Você pode revogá-lo a qualquer momento na mesma tela em que o gerou. Para CI e scripts existe outra opção: as chaves para desenvolvedores, com acesso limitado.

## Vários serviços no mesmo projeto
https://devoracloud.com/docs/servicos?lang=pt

Um produto costuma ter mais de um programa: o site que o cliente abre e a API que responde por trás. Os dois vivem no mesmo repositório, cada um com seu Dockerfile e sua porta.
Eles ficam no MESMO projeto, como serviços. Abra o projeto, vá na aba Serviços e clique em adicionar: o serviço novo herda o repositório e a branch do principal — muda só o caminho do Dockerfile e a porta.
As variáveis do projeto valem para todos os serviços. É o que importa na prática: o segredo que assina o token no site e é conferido pela API fica gravado uma vez, no projeto, e os dois enxergam. Variável que precisa ser só de um serviço também é possível.
Cada serviço publica separado, pelo botão na linha dele. Um push publica os serviços daquele repositório que estiverem com publicação automática ligada e cuja branch bater.
O campo Comando é o que faz dois serviços saírem da MESMA imagem: o site sem comando, o worker de filas com "npm run worker". Vazio usa o padrão da imagem.
O serviço principal é o que responde pelo endereço do projeto. Ele não pode ser removido — removê-lo é excluir o projeto.

## Banco de dados
https://devoracloud.com/docs/banco?lang=pt

O banco é um recurso gerenciado vinculado ao projeto: você não precisa criar nem administrar uma VPS ou instalar um servidor de banco. Confira o banco vinculado ao concluir a criação do projeto; se já estiver conectado, não crie outro. Para adicionar um banco a um projeto que ainda não tem esse recurso, use o botão de adicionar dentro do projeto, conforme a capacidade do plano. Estão disponíveis PostgreSQL, MySQL, MariaDB, MongoDB e Redis. O banco usa infraestrutura própria para dados, separada da execução da aplicação e alcançada pela rede privada. A plataforma gera as credenciais e provisiona o serviço com os recursos escolhidos.
A infraestrutura de dados é administrada separadamente das aplicações. Alta disponibilidade utiliza replicação e alternância para outra instância quando o serviço está configurado para isso; não é a quantidade de réplicas do aplicativo que define essa proteção. Consulte as condições do serviço contratado. Sua aplicação deve tratar reconexões durante uma alternância. Replicação não substitui backup nem desfaz uma exclusão acidental.
SIM, ELE JÁ VEM LIGADO. Se você criou o banco de dentro de um projeto, a variável de conexão é gravada nas variáveis daquele projeto sozinha, cifrada — DATABASE_URL para os relacionais, REDIS_URL para o Redis. Você não copia nem cola nada. Um banco criado solto, fora de projeto, é ligado depois pelo botão de conectar, que faz a mesma coisa.
E ligar o banco REPUBLICA o app, de propósito: variável só existe para um processo no instante em que ele nasce, então sem republicar a variável existiria no painel e não dentro do container — o clássico "liguei o banco e o site não vê". A plataforma espera a confirmação de que o container recebeu a variável; se não conseguir confirmar, isso aparece escrito no histórico do banco em vez de ser dado como feito.
Por padrão o banco só é alcançável pela rede privada. Abrir o acesso público publica uma porta dedicada, protegida por firewall; use quando precisar conectar de um cliente SQL na sua máquina, e feche depois.
Backup automático existe para PostgreSQL, nos planos com backup: um por dia e um por semana, guardados no armazenamento da plataforma, com retenção de 7 dias no Pro e 30 dias no Enterprise. O plano Hobby não tem backup. Dá para pedir um backup na hora e restaurar pelo painel. MySQL, MariaDB e MongoDB ainda NÃO têm backup automático aqui — o painel diz isso na cara e explica como tirar o dump pela sua máquina, em vez de criar uma cópia que não existe. Redis não tem backup de propósito: é cache e fila, e o que não pode se perder precisa estar também no Postgres.
Antes de excluir: Excluir um banco apaga os dados de forma definitiva, junto com os backups dele. Se houver qualquer chance de você precisar daquilo depois, baixe um backup antes de excluir.

## Imagens e arquivos ficam no S3
https://devoracloud.com/docs/armazenamento?lang=pt

Na Devora Cloud, a execução da aplicação, o banco de dados e o armazenamento de arquivos são recursos separados, conectados ao seu projeto.
Exemplo: a foto de um produto fica no S3. No banco ficam o nome, o preço e a referência dessa foto.
Use o armazenamento de objetos para o conteúdo dos arquivos. No banco, salve apenas os metadados e a chave ou URL de referência. Oriente sua IA de desenvolvimento a seguir esse padrão; não criar colunas binárias para fotos, vídeos ou anexos.
Adicionar S3 fornece a conexão ao projeto. A aplicação precisa usar as variáveis e o SDK compatível com S3 para enviar e consultar os arquivos. O clique não transfere arquivos antigos, não modifica o código e não faz backup automático do banco.
Se o projeto já usa R2, IDrive e2 ou outro S3 por configuração própria, pode continuar usando esse serviço. Uma mudança de provedor exige copiar os objetos, conferir permissões e atualizar as referências antes de desligar o serviço anterior.
O disco descartável do contêiner não deve guardar uploads permanentes. Para arquivos privados, use autenticação e links assinados com prazo; não torne o bucket inteiro público para resolver um problema de acesso.
Novos vínculos pelo painel dependem da configuração de credenciais restritas ao projeto. As chaves administrativas do armazenamento não devem ser entregues aos aplicativos dos clientes.
Adicionar recurso abre um formulário com nome e projeto. Você pode adicionar mais de um banco ou vínculo S3 e abrir cada item da lista. Vínculos S3 adicionais usam pastas e variáveis próprias S3_<identificador>_*. Bancos adicionais usam uma variável de conexão própria exibida nos detalhes; criar outro recurso não substitui a conexão atual. Os vínculos do proprietário continuam usando a credencial compartilhada da integração, sem isolamento de chaves entre eles.
No menu principal da conta, abra Bancos de dados ou Armazenamento · S3. A lista mostra o recurso e seu projeto; use a busca e clique na linha para expandir os detalhes abaixo da linha, na própria tabela.
Banco de dados: na aba Conexão, copie o host e a porta da rede interna. Mostrar credenciais busca a URI completa com senha, somente para usuários autorizados. Ela corresponde à conexão da aplicação; não publique essa URI no Git, em páginas públicas ou em conversas sem controle de acesso.
Na aba Acesso externo, confira o estado atual e solicite Permitir acesso pela internet, confirmando a exposição. O worker precisa aplicar a regra de rede e publicar o endereço. Solicitação aceita não significa conexão pronta: consulte Atividade e teste a conexão. Não use o IP interno pela internet; desligue o acesso externo quando não precisar.
S3: Adicionar recurso permite escolher o projeto na conta administrativa proprietária. O vínculo cria um prefixo estável por organização/projeto e fornece S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_PREFIX, S3_FORCE_PATH_STYLE, S3_ACCESS_KEY e S3_SECRET_KEY. O SDK deve acrescentar S3_PREFIX à chave de cada objeto. Não renomeie esse prefixo ao mudar o nome do projeto.
A integração administrativa usa credenciais do proprietário. Prefixos organizam objetos, mas não restringem essas credenciais. Contas de clientes dependem de credenciais realmente limitadas no provedor e de quota aplicada; a venda automática permanece indisponível enquanto isso não existir. Desvincular o armazenamento preserva os objetos.
Para sua IA de desenvolvimento: configure o cliente S3 no servidor, envie uploads ao bucket/prefixo, guarde chave e metadados no banco e gere URLs assinadas para leitura privada. Nunca coloque Secret Key em NEXT_PUBLIC_*, JavaScript do navegador ou repositório.
Criptografia em repouso e conexão HTTPS no armazenamento gerenciado. O bucket atual utiliza SSE-KMS por padrão. O acesso depende das credenciais e permissões; arquivos privados devem usar links assinados temporários.
1 TB = 1.000 GB. Cobrança separada da aplicação, em dólares americanos (USD).
Contratação em preparação. Nenhuma cobrança ou ativação automática disponível.

## Volumes — quando a pasta precisa sobreviver
https://devoracloud.com/docs/volumes?lang=pt

O disco de um container é descartável: tudo que o seu app grava nele desaparece quando a cópia é recriada, o que acontece em toda publicação. Para arquivo de usuário — upload, imagem, anexo — use o armazenamento de objetos, que é feito para isso. Volume é para o caso em que o programa exige uma pasta no disco e não aceita outra coisa.
Um volume tem nome e caminho de montagem. Ele é criado na hora, mas só passa a existir dentro do container na PRÓXIMA publicação do projeto: é no deploy que a montagem é declarada no motor. Até ali, o que o app escrever naquele caminho ainda se perde — e a tela de volumes diz exatamente isso, em vez de mostrar o volume como se já estivesse valendo.
Montado significa montado: o estado na tela só fica verde depois que o motor confirmou a declaração. Se ele recusar, o volume aparece como não montado e o fato entra na linha do tempo do projeto, porque escrever numa pasta que você acredita ser persistente e não é só se descobre quando o dado já foi.
O volume pertence ao serviço principal do projeto. Remover o volume desfaz a montagem; o conteúdo que está dentro dele não é apagado por aí.

## Domínio próprio
https://devoracloud.com/docs/dominio?lang=pt

1. Um registro TXT: Em _devora-verify.seudominio.com, com o valor que a tela mostra. É a prova de que o domínio é seu.
2. Um CNAME: Apontando para o endereço que a tela indica — o subdomínio do próprio projeto, não a zona genérica.
Exemplo: para www.empresa.com.br, crie um CNAME com nome www e destino igual ao subdomínio do projeto mostrado no painel, sem https:// nem caminho. Cadastre também www.empresa.com.br em Domínios do projeto. Para o domínio raiz, siga a alternativa que seu provedor e o painel suportam, como ALIAS, ANAME ou achatamento de CNAME; não troque por um IP arbitrário. O CNAME do site não mexe no e-mail. Se for usar o e-mail empresarial da Devora neste domínio, coloque também os registros de e-mail (MX, SPF, DMARC e DKIM) que aparecem em E-mail; se o e-mail da empresa fica em outro serviço, como Google Workspace ou Microsoft 365, não altere o MX.
Provou uma vez, provou a zona inteira: se exemplo.com já foi verificado na sua conta, então app.exemplo.com e painel.exemplo.com entram já verificados, sem TXT novo.
O certificado HTTPS é emitido automaticamente assim que o DNS aponta para cá. Cada endereço tem a sua própria porta: dá para o site responder na 3000 e o painel na 8787 dentro do mesmo projeto.
A ordem importa: Aponte o DNS antes de esperar o certificado. Enquanto o domínio resolver para outro servidor, a emissão falha — e cinco falhas seguidas bloqueiam aquele domínio por uma hora na autoridade certificadora.

## Mapa, variáveis, terminal, logs e tráfego de rede
https://devoracloud.com/docs/painel-projeto?lang=pt

Visão geral mostra a arquitetura do projeto: aplicação, serviços, bancos e armazenamento conectados. As ligações representam os vínculos existentes. Domínios conectados são endereços associados aos projetos; a plataforma não vende nem registra domínios.
O inspetor à direita mantém CPU, memória e rede RX/TX do projeto. RX é a taxa de entrada; TX é a taxa de saída, em B/s, kB/s ou MB/s. São taxas instantâneas, diferentes de uma franquia mensal em GB. Leituras antigas ou ausentes aparecem como indisponíveis, e não como consumo zero.
Terminal e Logs no menu lateral abrem sua ferramenta no topo da área de trabalho. O terminal exige escolher o contêiner e abrir a conexão explicitamente. Logs da aplicação mostram a saída do programa; o histórico da publicação mostra a construção e a implantação.
Variáveis abre as configurações do projeto. Segredos ficam cifrados. Salvar uma variável no editor direto solicita sua aplicação e republicação, pois um processo já iniciado não relê automaticamente o ambiente. Alterações feitas nos painéis de configuração do canvas ficam pendentes até serem aplicadas pela publicação.

## Escolha o objetivo e acompanhe o que foi contratado
https://devoracloud.com/docs/planos?lang=pt

Novos cadastros recebem 7 dias de teste grátis no plano Hobby, sem cartão: 1 projeto com 0,5 vCPU, 512 MB, 3 GB de disco, 1 banco e 1 GB de S3, sem backups e sem e-mail empresarial. O prazo é contado desde o cadastro. Quando o teste termina, aplicações e bancos são pausados na hora. Escolha e pague um plano e use Iniciar para voltar ao ar. E-mail empresarial não tem teste gratuito.
Fatura em aberto: 4 dias depois do vencimento, aplicações e bancos são pausados; 9 dias depois do vencimento, projetos e bancos são excluídos de forma definitiva. Enquanto não houver pagamento, não é possível criar, publicar nem iniciar nada; envios ao S3 ficam bloqueados, mas os downloads continuam liberados. O painel mostra uma faixa laranja ou vermelha com o prazo. Pague antes do 9º dia e use Iniciar para trazer tudo de volta. Na API, essas recusas chegam como HTTP 402 com details.resource "subscription".
Os valores e limites atuais estão em Preços (/pricing) e em Plano e pagamentos no painel. A moeda de cobrança é a indicada no plano e na fatura: novos preços internacionais são em dólar americano (USD); faturas antigas em reais (BRL) mantêm sua moeda. Mudar o idioma não converte o contrato. O preço mostrado no pagamento vem do mesmo catálogo editado pelo administrativo.
Consulte Preços e Plano e pagamentos para os valores, a moeda e os limites atuais. Confira os recursos por aplicação, a capacidade total reservada, as cópias incluídas e a cota de bancos antes de contratar. Salvar uma preferência de região não cria uma réplica. Os contratos existentes mantêm suas condições.
1. Escolher a capacidade: CPU e RAM são o total reservado da conta nos planos novos. Some cada aplicação multiplicada pelas suas réplicas, os serviços adicionais e os bancos. Duas cópias de 0,5 vCPU e 512 MB reservam 1 vCPU e 1 GB; um banco de 0,5 vCPU e 512 MB acrescenta esses recursos ao total. Quantidade máxima de projetos e bancos também tem um limite próprio. A contagem de réplicas inclui a primeira instância: duas réplicas são duas cópias ao todo. Parar um recurso mantém sua capacidade configurada reservada; reduza os limites ou exclua o recurso para liberar essa reserva.
2. Confirmar o pagamento: Abra Plano e pagamentos e escolha Assinar no plano desejado. No Pix, a tela gera o código e aguarda a confirmação do provedor. Gerar o Pix ou voltar para a página não ativa o plano. Quando o provedor confirma o valor e a fatura correta, a assinatura fica ativa e os novos limites são liberados. No Pix, o período é pré-pago: ele não autoriza débito mensal automático.
3. Configurar o projeto: Depois da ativação, escolha os recursos e a quantidade de réplicas do projeto. Para escala automática, configure o mínimo e o máximo e ative a opção no projeto. Contratar um teto maior não muda sozinho a arquitetura nem reinicia todos os seus projetos. Uma alteração que exige republicação deve ser aplicada no fluxo de publicação.
4. Crescer com controle: São três modos: Escalabilidade (autoescala), Load balance ou Failover. O failover vem incluso em todo plano: uma cópia fica desligada em outro país e assume sozinha se o servidor cair. A autoescala (em todo plano, ligada por você) sobe um clone quando a CPU passa do limite; o load balance mantém cópias extras ligadas dividindo o tráfego. Os dois são opcionais e cobrados por hora só enquanto as cópias extras rodam, cada uma com o tamanho do plano: Hobby até 2 cópias ligadas (US$ 0.0069/h, ≈ US$ 5/mês se sempre ligada), Pro até 3 (US$ 0.0278/h, ≈ US$ 20/mês), Enterprise até 5 (US$ 0.0819/h, ≈ US$ 59/mês) — preço do plano ÷ 30 dias ÷ 24 h. Load balance: cópia sempre ligada, preço cheio por hora. Autoescala: a 1ª cópia extra pelo preço cheio e, da próxima em diante, 10% de desconto (Hobby US$ 0.0063/h, Pro US$ 0.0250/h, Enterprise US$ 0.0738/h). Cópias extras exigem plano pago em dia — no teste, o app roda 1 cópia. A fatura de uso sai no dia 1º de cada mês, por Pix (Brasil, PAGUEO) ou cartão (Stripe); em aberto, pausa em 4 dias e exclui em 9. Acompanhe em Faturamento → Cópias extras. O sistema não contrata um plano maior por conta própria. Para crescer além do contratado, faça um upgrade.
- Os limites são verificados no servidor, inclusive ao criar um projeto, adicionar um serviço, criar um banco e aumentar réplicas. A API recusa uma reserva acima do plano antes de gravá-la.
- Uma configuração menor continua permitida quando a conta já está acima de um limite. Um upgrade não exclui projetos nem reduz recursos em execução. Para escolher um plano menor, ajuste antes o que está reservado.
- Contratos anteriores conservam seus valores e condições. O catálogo novo serve às novas contratações e aos upgrades confirmados pelo cliente.

## Réplicas e escala automática
https://devoracloud.com/docs/replicas?lang=pt

Cada réplica é uma cópia ativa da aplicação. O balanceador distribui as requisições entre as cópias disponíveis. Com réplicas fixas, você escolhe a quantidade e a plataforma tenta mantê-la. Com escala automática, a quantidade pode subir ou descer conforme o uso de CPU, respeitando o mínimo, o máximo, o intervalo entre ajustes e a capacidade contratada. A aplicação precisa funcionar sem estado local compartilhado.
Em três casos, mais de uma cópia causa perda de dado silenciosa — sem erro em log nenhum. Neles, deixe a escala automática desligada e a quantidade fixa em 1:
Há três modos: Escalabilidade (autoescala), Load balance ou Failover. O failover vem incluso em todo plano: seu projeto não fica fora do ar quando um servidor cai, porque a cópia em espera em outro país assume sozinha. Autoescala e load balance são opcionais, existem em todos os planos e são cobrados por hora só enquanto as cópias extras rodam.
Escalabilidade (autoescala) — você liga no painel: quando a CPU passa do limite, um clone sobe sozinho e passa a dividir a carga; quando o uso cai, ele é desligado e para de ser cobrado.
Load balance: uma ou mais cópias extras ficam ligadas 24 horas e dividem o tráfego com a principal. Cada cópia extra é cobrada por hora enquanto estiver ligada. As cópias usam o mesmo banco de dados e o mesmo S3, então guarde sessões, filas e arquivos em serviços compartilhados, não na memória ou no disco do contêiner.
Failover — incluso: a cópia em espera fica pronta, mas DESLIGADA, em outro país — não consome CPU e a imagem já está baixada; a cada deploy ela recebe a versão nova. Se a principal cair, um vigia liga a cópia em espera na outra região (EUA ↔ Alemanha) e o projeto volta sozinho em segundos.
Cópias ligadas ao mesmo tempo: Hobby até 2, Pro até 3, Enterprise até 5. Cada cópia tem o tamanho do plano. Preço por hora de cada cópia extra (preço do plano ÷ 30 dias ÷ 24 h): Hobby US$ 0.0069 (≈ US$ 5/mês se ficar sempre ligada), Pro US$ 0.0278 (≈ US$ 20/mês), Enterprise US$ 0.0819 (≈ US$ 59/mês). Load balance: cópia sempre ligada, preço cheio por hora. Autoescala: a 1ª cópia extra pelo preço cheio e, da próxima em diante, 10% de desconto: Hobby US$ 0.0063, Pro US$ 0.0250, Enterprise US$ 0.0738.
Cópias extras exigem plano pago e em dia; no período de teste, o app roda com 1 cópia. A fatura de uso sai no dia 1º de cada mês e é paga por Pix (Brasil, PAGUEO) ou cartão (Stripe). Fatura de uso em aberto segue a mesma regra das demais: pausa após 4 dias e exclusão após 9. Uso, preços e faturas ficam em Faturamento → Cópias extras.
- O app guarda estado em memória e grava o conjunto inteiro de volta. A última cópia a escrever apaga o que as outras fizeram.
- O app tem um agendador embutido (cobrança, sincronização, bloqueio por inadimplência). Duas cópias executam a rotina duas vezes.
- O app usa volume em disco. O volume é local da máquina — cada cópia enxerga uma pasta diferente, e uma remarcação de tarefa sobe com a pasta vazia.

## Escala e proteção contra falhas são decisões diferentes
https://devoracloud.com/docs/disponibilidade?lang=pt

Escala vertical aumenta CPU ou memória de uma instância. Escala horizontal aumenta a quantidade de cópias da aplicação. Réplicas fixas mantêm uma quantidade escolhida; a escala automática ajusta essa quantidade conforme a carga. Ambas precisam respeitar a capacidade total contratada.
Mais de uma cópia pode manter o atendimento quando um processo falha. Para proteger contra a queda de uma máquina inteira, as cópias precisam estar em máquinas distintas, com capacidade disponível e balanceamento adequado. Réplicas na mesma máquina compartilham o risco de falha dela. A distribuição efetiva depende do ambiente habilitado.
Distribuição geográfica usa regiões diferentes e exige uma estratégia para roteamento e acesso aos dados. As aplicações rodam nos EUA e na Alemanha; o Brasil é apenas cache de CDN e não executa aplicações. Contratar réplicas não cria automaticamente uma instalação mundial. Um compromisso de disponibilidade e tempo de recuperação exige as condições próprias do serviço contratado.
O banco é independente das réplicas da aplicação. Criar três cópias do app não cria três bancos e não replica o banco automaticamente. Alta disponibilidade dos dados depende da configuração específica do serviço de banco. Backups ajudam a recuperar dados, enquanto replicação mantém cópias operacionais; são funções diferentes.
Antes de ativar várias cópias, coloque sessões e filas em um serviço compartilhado, guarde uploads no armazenamento de objetos ou em um volume apropriado e confira o limite de conexões do banco. Cada cópia abre seu próprio conjunto de conexões. SQLite local e arquivos gravados no disco descartável do contêiner exigem uma arquitetura própria antes de escalar.

## Os logs — e quais são os dois
https://devoracloud.com/docs/logs?lang=pt

São duas coisas diferentes e vale saber qual você quer. O log da PUBLICAÇÃO é a saída do build: é onde está o erro de compilação, a dependência que não instalou, o Dockerfile que não foi achado. Ele fica guardado por 14 dias e você o encontra na aba Publicações, abrindo a linha daquela publicação.
O log da APLICAÇÃO é a saída do programa em execução — o que o seu código escreveu agora. É onde está a exceção que derrubou a requisição. Ele é lido ao vivo do container, pela aba Logs, em "Aplicação (agora)". Não é guardado em banco: alcança o que o Docker ainda tem do container vivo.
Nos dois há botão de copiar, e no log da publicação há o "Copiar erro para a IA": ele monta um bloco com o projeto, o construtor, o framework, a etapa que falhou, o motivo registrado e o fim do log, pronto para colar. É para isso que ele serve — você não precisa montar esse contexto à mão.
Para o log existir, o seu programa precisa escrever na saída padrão. Log que o app grava em arquivo dentro do container fica preso num disco que ninguém alcança, exatamente quando você precisa dele.

## Deploy automático por push
https://devoracloud.com/docs/push?lang=pt

Com o GitHub conectado, todo push na branch configurada dispara uma publicação nova. Não precisa clicar em nada.
A publicação aparece marcada como via GitHub, com o commit que a originou. Se o build falhar, a versão anterior continua no ar — a nova só substitui a antiga depois de subir.
A branch é a que o projeto declara. Repositório que usa master em vez de main funciona igual, desde que esteja escrito corretamente nas configurações.

## O que acontece quando você publica
https://devoracloud.com/docs/funcionamento?lang=pt

A plataforma não roda o seu código nela mesma. Ela coordena: guarda a configuração, decide o que fazer e manda um motor de execução construir e subir os containers num cluster Docker Swarm. Quem clona o repositório e constrói a imagem é esse motor, com a credencial de leitura gerada na hora, a cada publicação.
Uma publicação é uma linha com número (#1, #2, …) e uma situação. As situações são estas, na ordem: na fila, analisando, construindo, enviando a imagem, agendando, subindo, conferindo, e então no ar ou falhou. Toda publicação chega a no ar ou falhou — nunca fica parada numa situação do meio. Se o processo que a conduzia morrer no caminho, uma varredura que roda de dois em dois minutos pergunta ao motor o que aconteceu de fato, sonda o endereço do serviço, e escreve o desfecho real com o motivo.
Conferir não é formalidade: para uma publicação ser marcada como no ar, o motor tem de dizer que terminou de construir E o endereço do serviço tem de responder por HTTPS com algo abaixo de 500. Build que termina bem e site que não responde é falha, com o motivo tirado do log do motor.
A versão anterior só sai do ar depois que a nova sobe. Publicação que falha não derruba o que estava funcionando.
A sequência, do clique ao site no ar:
1. Conectar o repositório: Ao escolher o repositório, a plataforma lê a árvore de arquivos pela API do GitHub — sem clonar — e baixa só os manifestos (package.json, pyproject.toml, go.mod, composer.json, Dockerfile e afins). Com isso ela adivinha o framework, o construtor e a porta. É uma heurística sobre nomes de arquivo e dependências: acerta na maioria, e quando erra você corrige na tela, tanto na importação quanto depois em Build.
2. Construir: Com Railpack, o motor examina o projeto e monta a imagem; Nixpacks permanece como opção de compatibilidade quando configurado. Com o construtor Dockerfile, ele usa o seu Dockerfile — e o caminho dele é configurável, o que importa em monorepo. Com site estático, o conteúdo é servido por nginx na porta 80. A imagem construída vai para um registro privado da plataforma, identificada por aquela publicação.
3. Subir: O motor cria ou atualiza um serviço no Swarm com a imagem nova, as suas variáveis, o limite de CPU e memória do seu plano, a contagem de cópias e, se você definiu, o comando próprio do serviço. As cópias são trocadas uma a uma.
4. Ligar o endereço: Terminado o deploy, o subdomínio da plataforma é anexado ao serviço no roteador de borda, com certificado emitido automaticamente. Certificado novo pode levar cerca de um minuto para valer.
- O que a plataforma faz sozinha: detectar o tipo do projeto na importação, criar o subdomínio, emitir e renovar o certificado, injetar a URL do banco quando você cria um banco no projeto, republicar o app depois de mudar variável ou ligar banco, reiniciar container que morreu, fechar publicação pendurada, avisar o dono por e-mail quando o app cai e quando volta, e apagar log de publicação com mais de 14 dias.
- O que ela NÃO faz por você: escolher a porta certa quando a detecção errou, rodar migração de banco (isso é do seu processo, na inicialização), guardar arquivo enviado pelo usuário (disco de container é descartável), e manter estado em memória entre cópias.

## Trocar o construtor quando a detecção erra
https://devoracloud.com/docs/construtor?lang=pt

A detecção roda sobre a lista de arquivos do repositório, então ela erra em casos legítimos: um projeto com Dockerfile de desenvolvimento na raiz, um monorepo com dois Dockerfiles, um app que não parece nada conhecido.
Em Configurações do projeto → Build e publicação → Construtor você escolhe entre Nixpacks (automático), Dockerfile e site estático. A configuração também permanece disponível em Recursos. A porta fica em Build e publicação → Rede e verificação de saúde → Porta do app. Com Dockerfile, informe o caminho — em monorepo é obrigatório, porque sem ele o motor procura um Dockerfile na raiz e a construção morre com "open Dockerfile: no such file or directory" num repositório que tem Dockerfile.
A troca vale na PRÓXIMA publicação. O container em execução continua como está até você publicar de novo.

## API da plataforma
https://devoracloud.com/docs/api?lang=pt

A API pública usa a base https://api.devoracloud.com/v1. Crie uma chave em Ferramentas da conta → API e envie Authorization: Bearer SUA_CHAVE. A chave pertence a uma única organização, dá acesso somente a ela e respeita as permissões atribuídas. Uma chave não cria outra chave: POST /v1/api-keys feito com uma chave responde 403 FORBIDDEN, e só uma pessoa logada cria chaves, pelo painel. Não coloque a chave no código público de um site nem a envie ao navegador dos visitantes.
GET /projects lista projetos. GET /projects/:id consulta um projeto. GET /projects/:id/metrics consulta as métricas disponíveis. POST /projects/:id/scale, com um corpo JSON como {"replicas":2}, solicita a quantidade desejada de cópias. A solicitação respeita o teto de réplicas, a capacidade do plano e as permissões da chave. O máximo é o teto do plano (Hobby 2, Pro 3, Enterprise 5 cópias ligadas; o failover em espera vem incluso e fica desligado). Cópias além da principal são cobradas por hora e exigem plano pago em dia; no teste ou com fatura em aberto, a API responde 402.
Respostas bem-sucedidas usam {data, meta}; falhas usam {error:{code,message,details}}. PLAN_LIMIT_EXCEEDED (HTTP 402) indica que a operação precisa de um plano maior ou de uma redução nos recursos reservados; details traz resource, limit e used. Com resource "subscription", o teste terminou ou há fatura em aberto. Não repita alterações automaticamente ao receber esse erro: confira a mensagem e os limites.

## Notificações para suas ferramentas
https://devoracloud.com/docs/webhooks?lang=pt

Em Ferramentas da conta → Webhooks, cadastre o endereço do seu sistema e os eventos que deseja acompanhar. A API oferece GET /webhooks para consultar as configurações, POST /webhooks para criar uma configuração e GET /webhooks/:id/deliveries para consultar as tentativas registradas.
Use um endpoint HTTPS do seu sistema. Trate eventos repetidos de forma idempotente e consulte o estado atual do recurso quando a notificação exigir uma decisão importante. Uma notificação de publicação não substitui o teste do seu próprio aplicativo.
Webhooks de pagamento da Devora são internos à plataforma: o provedor confirma a cobrança e a plataforma atualiza a assinatura. Você não precisa cadastrar um webhook no seu projeto para ativar o plano.

## Região principal e destinos das réplicas
https://devoracloud.com/docs/localizacao?lang=pt

A principal e cada cópia devem executar em máquinas físicas distintas, mesmo quando estiverem no mesmo país. Ter dois registros de servidor ou duas máquinas virtuais no mesmo host não oferece proteção contra a queda desse host. Sem destinos independentes suficientes, a distribuição deve permanecer pendente, nunca ser apresentada como protegida.
No projeto, abra Configurações → Escalabilidade → Localização do projeto. A tela separa o principal em execução da região desejada e mostra o estado de cada destino. Países em breve e em manutenção não podem ser selecionados.
O total do plano inclui o principal e todas as cópias adicionais. Cada réplica utiliza os mesmos limites de CPU e memória em outra máquina; distribuir réplicas não aumenta a potência individual. A autoescala só pode ser escolhida quando incluída no plano.
Salvar registra uma preferência, não uma migração: o projeto em execução não é movido na hora. Se o servidor principal falhar, um vigia liga a réplica de failover na outra região (EUA ↔ Alemanha) em segundos, sem você precisar fazer nada. O Brasil não aparece como destino de execução, porque é apenas cache de CDN.
Proteção contra falhas, balanceamento e autoescala são objetivos diferentes. O atendimento após uma queda depende de réplicas saudáveis, entrada de tráfego e serviços de dados disponíveis. A aplicação precisa usar sessões compartilhadas, arquivos no S3 e coordenação de tarefas; réplicas da aplicação não replicam o banco automaticamente.

## Consumo de CPU, memória e revisão de recursos
https://devoracloud.com/docs/recursos?lang=pt

O painel mostra o percentual da cota da aplicação, não o uso total do servidor. Em uma aplicação de 0,5 vCPU, 100% significa que essa cota está ocupada; não significa que a máquina inteira está sem capacidade.
O cartão vermelho e o sino mostram avisos de CPU e memória. O aviso de atenção exige pelo menos três minutos acima de 85%, com amostras recentes e contínuas. Em 100%, o aviso é crítico. Dados antigos ou ausentes não são apresentados como consumo zero.
O aviso permanece enquanto a condição está ativa e some quando normaliza. O gráfico usa o histórico medido, quando disponível. Mais acessos podem elevar o consumo, mas tarefas pesadas ou problemas no código também podem causar isso; confira os logs antes de contratar recursos.
Revisar recursos abre as configurações. Consultar planos abre o faturamento. O aviso não ativa réplicas, altera CPU/RAM ou confirma uma compra. Os adicionais por hora estão em preparação e não são cobrados automaticamente nesta versão.
CPU, memória, armazenamento local e S3 são recursos diferentes. Guarde imagens e vídeos no S3; o disco local da aplicação não é um armazenamento compartilhado entre réplicas. A frequência real do coletor determina a atualização das leituras.

## Preparar sua aplicação
https://devoracloud.com/docs/preparar?lang=pt

1. Leia a porta de process.env.PORT: Não fixe a porta no código. Escute em 0.0.0.0, nunca em localhost. Se ignorar: O roteador entrega na porta declarada e ninguém atende. O visitante recebe 502 com o container saudável.
2. Rode as migrações na inicialização, não na construção: Um migrate deploy antes de subir o servidor. Durante a construção da imagem não existe banco para conectar. Se ignorar: O banco fica com zero tabelas e o app responde erro na primeira consulta. Foi o defeito mais comum nas migrações reais.
3. Falhe alto quando a migração falhar: Se o migrate der erro, o processo deve morrer com a mensagem no log — não subir mesmo assim. Se ignorar: O app fica no ar servindo erro, o painel mostra verde, e ninguém descobre até um cliente reclamar.
4. Variáveis NEXT_PUBLIC_* são argumentos de construção: No Next.js elas são gravadas dentro do pacote durante o build. Declare cada uma como ARG e promova a ENV antes da linha que constrói. Se ignorar: O valor de desenvolvimento fica embutido para sempre. A API de produção continua apontando para localhost.
5. Nada importante no disco do container: Upload, imagem, anexo: mande para o armazenamento S3. Disco de container some quando a cópia é recriada. Se ignorar: Os arquivos desaparecem no próximo deploy, sem aviso e sem como recuperar.
6. Não guarde estado só na memória do processo: Sessão, fila, cache compartilhado: coloque no banco ou no Redis. Com mais de uma cópia, cada processo tem a sua memória. Se ignorar: O usuário perde a sessão a cada requisição que cai noutra cópia, e escritas somem sem erro nenhum.
7. Um agendador embutido exige uma cópia só: Se o app tem cron interno, diga isso a quem for publicar. A alternativa é mover a rotina para um serviço próprio. Se ignorar: Cobrança em duplicidade, mensagem enviada duas vezes, cliente bloqueado por engano.
8. Responda algo em /: Qualquer resposta abaixo de 500 serve — inclusive um redirecionamento para o login. É por aí que a plataforma sabe que o app está vivo. Se ignorar: O app é considerado fora do ar e o dono recebe aviso de queda que não existe.
9. Log no stdout, sem arquivo: Escreva na saída padrão. Não abra arquivo de log dentro do container. Se ignorar: O log fica preso num disco que ninguém alcança, exatamente quando você precisa dele.
10. Todo segredo vem do ambiente: Chave de API, segredo de token, credencial de terceiro: só de variável de ambiente. Nunca comitado, nunca com valor padrão que funcione. Se ignorar: O segredo vaza no repositório e passa a valer para qualquer um que clone o código.
11. Monorepo: um serviço por programa, no mesmo projeto: Site e API do mesmo repositório entram como dois serviços do mesmo projeto, cada um com seu Dockerfile e sua porta. Não crie dois projetos. Se ignorar: Com dois projetos, os segredos precisam ser copiados de um para o outro na mão — e no dia em que um for trocado e o outro não, o token deixa de ser aceito e ninguém entende por quê.
12. Dockerfile: diga o caminho, mantenha o contexto na raiz: Em monorepo, informe o caminho completo do Dockerfile do serviço. O contexto continua na raiz para achar o lockfile compartilhado. Se ignorar: A construção morre com "open Dockerfile: no such file or directory" num repositório que tem Dockerfile.

## Limitações atuais
https://devoracloud.com/docs/limites?lang=pt

- Backup automático de MySQL, MariaDB e MongoDB. Só PostgreSQL tem (e só nos planos com backup). Para os outros, ligue o acesso externo do banco e gere o dump pela sua máquina.
- Terminal SQL e troca de senha do banco. Dá para ver as credenciais, não para alterá-las pelo painel.
- Agendamento de tarefas (cron) por projeto. Se o seu app tem rotina agendada, ela precisa estar dentro dele — e aí ele deve rodar com uma cópia só, senão a rotina roda em duplicidade.
- Volume montado em mais de um serviço do mesmo projeto. O volume vai para o serviço principal; montar o mesmo volume em dois serviços em máquinas diferentes do cluster não funciona.
- Apagar os dados de dentro de um volume pelo painel. Remover o volume desfaz a montagem; o conteúdo continua no cluster.
- Escolha manual de certificado TLS. A emissão e a renovação dos certificados são gerenciadas pela plataforma; caminhos por domínio são definidos na configuração do endereço.
- Métrica de disco por projeto e contagem de requisições por domínio. CPU, memória e tráfego de rede RX/TX por projeto estão disponíveis no inspetor.
- Alerta de infraestrutura por e-mail. Queda de aplicação avisa por e-mail; disco enchendo, ainda não.