# 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 English (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 — Devora manual

What is Devora Cloud?
Devora Cloud is a Brazilian cloud hosting platform from the Klaup group, built to publish everything from simple websites to complete applications. It brings project deployment, managed databases, S3 storage, a terminal and CPU, memory and network monitoring together in one dashboard.
The platform offers AI-assisted build failure analysis and documentation to help diagnose issues and integrate services. Suggestions should be reviewed before changing code.
Country expansion covers primary region selection, replicas and autoscaling according to the plan, application compatibility and available infrastructure. Operations are currently in the United States; other locations are marked as planned on the map. Saving a region preference does not perform a migration.
https://devoracloud.com/about?lang=en

How to deploy, connect services and troubleshoot Devora Cloud.
https://devoracloud.com/docs?lang=en

## How Devora Cloud is organized
https://devoracloud.com/docs/estrutura?lang=en

An organization is your account. Projects group applications, services, domains, environment variables, storage and linked databases. A repository with a frontend and API can use two services in the same project.
Devora coordinates deployment and resource configuration. Database infrastructure is managed separately from application execution. Customers do not need to install or administer a database server. Each linked database has its own connection details.

## Help before opening a ticket
https://devoracloud.com/docs/suporte?lang=en

Describe the problem in Support. Relevant guidance appears before sending a ticket; no ticket is created just by reading suggestions. If it does not help, send the ticket with your project, deployment, time, error and attempted checks.
For build failures, open Problems and use the available AI analysis. It explains possible causes without automatically repairing code. Use Copy error for AI when available and share the sanitized context with your development AI or support. Never share passwords, tokens or credential-bearing connection URLs.

## Deploy from GitHub
https://devoracloud.com/docs/publicar?lang=en

Connect GitHub, choose the repository and branch, then check the detected builder and port before deploying. Available builders are automatic Nixpacks, Dockerfile and static site. Detection is a suggestion that may need correction.
The platform builds the application image, deploys it and connects a generated project subdomain with HTTPS. A static site does not need a database. Check whether a database is already linked before requesting another, and confirm that your plan permits it.

## Publish and manage with your AI
https://devoracloud.com/docs/ia?lang=en

Any AI that can read a web page and call an API — ChatGPT, Claude, Gemini, Cursor, GitHub Copilot, Windsurf and others — can create the project, database and storage, upload your code and publish it for you. No Git, no Docker: you chat, it does the work.
Access is granted with an AI token generated in your dashboard. With it, the AI reads the manual written for it at https://devoracloud.com/llms.txt and uses the Devora API on behalf of your account.
1. Create your account: The free trial lasts 7 days on the Hobby plan and requires no card.
2. Generate the AI token: In the dashboard sidebar, open "AI token & API" and click "Generate AI token".
3. Paste the ready-made text into your AI: Copy the text shown on screen — it already contains the token and the link to the AI manual (https://devoracloud.com/llms.txt) — and paste it into the chat with your AI.
4. Answer the AI’s questions: Before publishing, the AI asks for the project name, whether you need a database, whether you need to store files (S3 storage) and the region.
5. Get the live address: The AI follows the build and, when it finishes, sends you the published address: https://<name>.apps.devoracloud.com.
What the AI can do with the token: list and create projects; create a PostgreSQL, MySQL, MariaDB, MongoDB or Redis database (DATABASE_URL, or REDIS_URL for Redis, is injected into the app); turn on private S3 storage (S3_* variables); upload a ZIP of the code and deploy it; read the build logs and the failure diagnosis; read runtime logs, CPU and memory metrics, restarts and S3 usage to tell you whether you need more processor, memory or space; add custom domains; and set environment variables.
What the AI cannot do: pay for or change your plan, or buy storage packs — you do that yourself in Billing or Storage. It cannot create API keys either: only you, logged in to the dashboard. Apps run in the USA and in Germany; Brazil is only Devora’s own CDN cache, not a place where apps run.
Example text to paste into your AI: "My hosting is Devora Cloud. Read the AI manual at https://devoracloud.com/llms.txt and use this token: dc_live_… Publish my project, asking me first about database, S3 storage and region."
If something goes wrong:
- Free trial ended or invoice unpaid: apps and databases are paused; pay for the plan and use Start. An invoice 9 days overdue leads to permanent deletion.
- Plan limit reached: the AI tells you which resource is over the limit; reduce usage or choose a bigger plan.
- Deploy failed: the AI reads the build diagnosis, fixes the code and deploys again.
- Storage full: buy a storage pack or choose a bigger plan.
Token security: The token is shown only once and gives full access to this organization — and only this one. It cannot create other keys. Never publish it or share it anywhere public. You can revoke it at any time on the same screen where you generated it. For CI and scripts there is a separate option: developer keys, with limited access.

## Multiple services in one project
https://devoracloud.com/docs/servicos?lang=en

Use services for programs that belong together, such as a frontend, API and worker. Each service has its own Dockerfile path, port and optional start command. A worker can reuse an image with a different command.
Project variables are shared with its services; service-specific variables may be configured separately. Deployments belong to the service being published. Avoid duplicating a project solely to run another process from the same repository.

## Managed databases and connection details
https://devoracloud.com/docs/banco?lang=en

Use the database already linked to the project; do not install PostgreSQL or MySQL inside the application container. Managed data infrastructure is separate from app replicas. Add a database only when the project needs one and does not already have it. Available engines: PostgreSQL, MySQL, MariaDB, MongoDB and Redis. Automatic backups exist for PostgreSQL only, and only on plans with backup (Pro 7 days, Enterprise 30 days; Hobby has none).
When a database is linked from the project, its encrypted connection variable is added automatically and the app is redeployed to receive it. Use the supplied variable and private host. Table creation and schema migrations remain part of your application deployment process.
Database high availability requires database replication and failover in the configured data service. Application replicas do not create database replicas. Reconnect after a failover; replication does not replace backups or undo accidental deletion. Check the conditions of the service.
Public access is optional and should only be enabled when needed for an external SQL client. Before deleting a database, export any data you need to keep. Do not delete it to troubleshoot a connection.

## Store images and files in S3
https://devoracloud.com/docs/armazenamento?lang=en

Devora Cloud keeps application execution, databases and file storage as separate resources connected to your project.
Example: a product photo lives in S3. The database stores the name, price and reference to that photo.
Store file contents in object storage. Keep only metadata and the object key or URL in the database. Tell your development AI to follow this pattern, without binary columns for photos, videos or attachments.
Adding S3 provides connection settings. Your application must use those settings and an S3-compatible SDK to upload and retrieve files. Clicking does not migrate old files, change code or back up the database.
An app already using R2, IDrive e2 or another S3 service can keep using it. Changing providers requires copying objects, checking permissions and updating references before retiring the old service.
Do not use disposable container files for permanent uploads. Use authentication and expiring signed links for private files; do not make the entire bucket public to fix access.
New panel connections depend on project-restricted credentials. Storage administration keys must not be distributed to customer applications.
Add resource opens a form with name and project. Multiple databases and S3 links appear as separate list rows. Additional S3 links use separate prefixes and S3_<identifier>_* variables. Additional databases receive their own connection variable shown in details; adding a resource preserves existing connections. Owner links still share integration credentials; prefixes do not isolate those credentials.
Open Databases or Storage · S3 in the account menu. Search the resource list and click a row to expand its details below the row in the same table.
Database: Connection shows the private host and port. Show credentials retrieves the full password-bearing URI for authorized users only. Never publish it in Git, public pages or uncontrolled conversations.
External access: check the current state, request internet access and confirm exposure. The worker must apply network rules and publish an address. An accepted request does not mean connectivity is ready: check Activity and test. Private IP addresses do not work over the internet. Disable external access when no longer needed.
S3: the owner administrator can select a project when adding storage. The link provides a stable organization/project prefix and S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_PREFIX, S3_FORCE_PATH_STYLE, S3_ACCESS_KEY and S3_SECRET_KEY. Your SDK must prepend S3_PREFIX to object keys.
Owner integration uses owner credentials. Prefixes organize objects but do not restrict those credentials. Customer sales require provider-restricted credentials and enforced quotas; automatic ordering remains unavailable until these exist. Unlinking storage preserves objects.
Development AI: configure the S3 client on the server, upload to the bucket/prefix, store keys and metadata in the database and issue signed URLs for private reads. Never place secret keys in NEXT_PUBLIC_*, browser JavaScript or Git.
Encryption at rest and HTTPS connections for managed storage. The current bucket uses SSE-KMS by default. Access depends on credentials and permissions; private files should use expiring signed links.
1 TB = 1,000 GB. Billed separately from applications, in US dollars (USD).
Ordering is being prepared. No automatic charges or activation are available.

## Persistent files and volumes
https://devoracloud.com/docs/volumes?lang=en

Container files are disposable. Use object storage for uploads and media; use a volume when the program specifically requires a persistent filesystem path.
A volume mount applies on the next deployment. Check that the engine confirmed the mount. A local volume cannot be treated as a shared filesystem across application replicas on different machines.

## Custom domain and project subdomain
https://devoracloud.com/docs/dominio?lang=en

Open the project Domains section and add your domain without protocol or path. Prove ownership using the TXT record shown in the panel. Point the CNAME to the specific project subdomain shown there, not to the general platform zone.
Example: for www.example.com, create a CNAME named www with the project subdomain as target, without https://. For the apex domain, follow the supported ALIAS, ANAME or CNAME-flattening instructions of your DNS provider and panel. Do not guess an IP.
Allow DNS propagation before checking HTTPS. The certificate is issued and renewed automatically when routing is correct. The site CNAME does not touch email. If you will use Devora business email on this domain, also add the email records (MX, SPF, DMARC and DKIM) shown under Email; if your company email lives on another service, such as Google Workspace or Microsoft 365, do not change the MX.

## Business email, DNS and mail apps
https://devoracloud.com/docs/email?lang=en

1. Fix blocked sending (Relay access denied): If receiving works but sending shows Relay access denied, open the outgoing SMTP settings. Use port 587, STARTTLS, Normal password and your full email address as username. Port 25 is for server-to-server delivery, not mail apps. Ensure this account actually uses that outgoing server. Use the mailbox password, which can differ from your dashboard password. Never share passwords in a ticket. Automatic setup in mail apps uses the domain’s autoconfig/autodiscover CNAME and SRV records (see Configure DNS records). They work even if the website is hosted outside Devora. Existing accounts may need a one-time SMTP correction.
2. Open the account or project menu: Open Business email in the account menu or within a project. Projects organize the link and suggest connected domains. Use a domain you own; the application’s free subdomain is not your business email domain.
3. Review the subscription and payment: Email is separate from hosting, billed in BRL per mailbox for 30-day periods, without a free trial. Choose the quantity and review price and quota. Generate and pay Pix: only payment confirmed with the provider activates mailboxes. Pending payment or clicking a button grants no access. The actual owner administrator has a server-validated courtesy action that creates no invoice.
4. Understand upgrades and renewals: Increasing quantity during a paid period credits the proportional remaining time and starts a new 30-day period after payment. Renewing the same quantity adds 30 days to the current expiry. Quantity reductions must wait until the active period ends; do not delete accounts to bypass licensing.
5. Add and verify your domain: Add your domain, optionally selecting its project. First publish only the ownership TXT at _devora-mail.yourdomain and verify it. With an active service and valid proof, the panel configures the mail domain and provides DKIM. A domain already on the mail server requires explicit owner-administrator adoption; existing mailboxes are never imported or overwritten automatically.
6. Configure DNS records: Click a domain row for DNS settings and create exactly these records: TXT _devora-mail.yourdomain = verification token; MX yourdomain 10 mail.bytsend.com (incoming mail); TXT yourdomain "v=spf1 mx ~all" (SPF, authorizes sending); TXT _dmarc.yourdomain "v=DMARC1; p=none" (DMARC); and the DKIM TXT, which appears after verification (signs messages). For automatic setup in Outlook, Thunderbird and mobile: CNAME autoconfig.yourdomain and autodiscover.yourdomain → 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. These records work even if the website is hosted outside Devora. Keep a single SPF record by merging authorized services. Website CNAME records do not configure email. Plan migration before changing an existing MX.
7. Create a mailbox: After domain verification, choose Add mailbox, select the domain, enter the name before @ and a password of at least 12 characters. Mailbox count cannot exceed the license. Passwords are not returned by the API or stored as plaintext in Cloud. Use Change password when needed. Retry failed creation with the same address and password; existing accounts cannot be overwritten.
8. Use webmail, Outlook or mobile: Use Open webmail or configure Outlook, Thunderbird or mobile: full email address as username, mailbox password, incoming IMAP mail.bytsend.com port 993 with SSL and outgoing SMTP mail.bytsend.com port 587 with STARTTLS and authentication. Automatic setup depends on the app and version. The mailbox password is independent from your Cloud password.
9. Check quota and service validity: Quota applies per mailbox and appears before payment. Admin price and quota edits apply to new orders and renewals. At expiry, managed-account access is suspended while messages are preserved; renewal restores service. Existing unmanaged mailboxes are not changed by this lifecycle.
10. Manage imported mailboxes: Imported mailboxes: after an administrator links an existing mailbox, it appears under Email accounts. Messages and the current password remain on the server; importing does not migrate or recreate the mailbox. Linking a project organizes the account without changing its email address. Owner-administrator courtesy creates no charge.
11. Change the password securely: Change password: open Business email, find the address under Email accounts and choose Change password. Enter a new password of 12–128 characters and click Save password. The previous password cannot be displayed. After a successful save, update the password in Outlook, mobile and other mail apps; new webmail logins also use it. Changing the password preserves messages and does not change your Cloud login password.
12. Troubleshoot and get help: For your AI or support, provide domain, affected address, login/sending/receiving failure, time, error, service state and whether webmail works. Never provide passwords or private message content. Test sending and receiving with an external address after DNS setup.
13. Update routing after migration: Routing and migration: use the server hostname, public IP and webmail currently shown in the panel, not an old IP from screenshots. MX targets a DNS hostname, not an IP. Administrators update addresses in Admin → Business email. This updates instructions; it does not migrate mailboxes or change DNS. With the same hostname, clients keep MX while the administrator updates server A/AAAA. A changed hostname requires updating MX and mail apps. Configure the private connection and key in Admin → Integrations. Refresh and reopen the domain for current instructions.

## Project map, variables, metrics and terminal
https://devoracloud.com/docs/painel-projeto?lang=en

The project map shows actual connections between services. The inspector displays CPU, memory and RX/TX network rates. RX is inbound traffic and TX is outbound, measured as a rate rather than a monthly GB allowance. Missing data is not zero usage.
Terminal and Logs open their tools from the sidebar. Select the service and connect the terminal explicitly. Variables affect a process when it starts; configuration changes may require deployment. Keep secrets out of logs and support tickets.

## Plans, capacity and payment
https://devoracloud.com/docs/planos?lang=en

New accounts get a 7-day free trial on the Hobby plan, counted from registration, with no card: 1 project with 0.5 vCPU, 512 MB, 3 GB disk, 1 database and 1 GB S3, no backups and no business email. When the trial ends, apps and databases are paused right away. Pay for a plan, then use Start to resume. Business email has no free trial.
Unpaid invoice: 4 days after the due date, apps and databases are paused; 9 days after the due date, projects and databases are permanently deleted. While unpaid you cannot create, deploy or start anything; S3 uploads are blocked but downloads still work. The dashboard shows an orange or red banner with the deadline. Pay before day 9 and use Start to bring everything back. In the API these refusals are HTTP 402 with details.resource "subscription".
Current prices, currency and limits are shown in Pricing and Plan and payments. Check the application size, total reserved capacity, included copies and database allowance before contracting. A saved region preference does not create a replica. Existing contracts keep their conditions.
Capacity is shared across the account. Count each app’s resources multiplied by its replica count, plus databases and other services. Replica counts include the first instance. An upgrade increases the available limits; configure project resources and replicas afterwards.
Pix is prepaid and activation follows verified provider confirmation. Generating a Pix code does not activate a plan and does not authorize automatic monthly debits. Avoid paying again until the existing payment status is checked.

## Application replicas and autoscaling
https://devoracloud.com/docs/replicas?lang=en

A replica is a running copy of the application. Fixed replicas keep a configured count; autoscaling adjusts it within minimum, maximum and plan capacity. Failover is included in every plan (a standby copy kept off in another country); autoscaling and load balancing are optional and billed by the hour. Copies running at once: Hobby up to 2, Pro up to 3, Enterprise up to 5, each extra copy billed by the hour while it runs. Extra copies do not repair application errors.
Keep sessions, queues and mutable data in shared services. A local SQLite file, local upload folder or embedded scheduler needs special care before scaling: copies can diverge or execute the same scheduled action twice.
There are three modes: Scalability (autoscaling), Load balancing or Failover. Failover is included in every plan: your project stays online when a server goes down, because the standby copy in another country takes over on its own. Autoscaling and load balancing are optional, available on every plan and billed by the hour only while the extra copies run.
Scalability (autoscaling) — you turn it on in the dashboard: when CPU goes over the limit, a clone starts on its own and shares the load; when usage drops, it is turned off and stops being billed.
Load balancing: one or more extra copies stay on 24 hours and share the traffic with the primary. Each extra copy is billed by the hour while it is on. The copies share the same database and S3, so keep sessions, queues and files in shared services, not in the container’s memory or disk.
Failover — included: the standby copy is ready but kept OFF in another country — it uses no CPU and its image is already downloaded; every deploy updates it. If the primary fails, a watcher starts the standby in the other region (USA ↔ Germany) and the project comes back on its own within seconds.
Copies running at once: Hobby up to 2, Pro up to 3, Enterprise up to 5. Each copy has the plan’s size. Hourly price of each extra copy (plan price ÷ 30 days ÷ 24 h): Hobby US$ 0.0069 (≈ US$ 5/month if always on), Pro US$ 0.0278 (≈ US$ 20/month), Enterprise US$ 0.0819 (≈ US$ 59/month). Load balancing: always-on copy at the full hourly price. Autoscaling: the 1st extra copy at full price and, from the next one on, 10% off: Hobby US$ 0.0063, Pro US$ 0.0250, Enterprise US$ 0.0738.
Extra copies require 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 follows the same rule as any other: paused after 4 days, deleted after 9. Usage, prices and invoices are in Billing → Extra copies.

## Availability, distribution and backups
https://devoracloud.com/docs/disponibilidade?lang=en

Vertical scaling increases CPU or RAM; horizontal scaling adds app copies. Protection against a host failure requires copies on different hosts, suitable routing and spare capacity. Applications run in the USA and in Germany; Brazil is CDN cache only and does not run apps.
Database replication and failover are a separate data-service configuration. Backups recover earlier data; replication maintains operational copies. Neither application replicas nor database replication alone promise zero downtime in every failure.

## Build logs and application logs
https://devoracloud.com/docs/logs?lang=en

Deployment logs show dependency installation, compilation and image/deploy failures. Open the failed publication to inspect them. Application logs show the running program’s output; use them for runtime exceptions and connection failures.
Open Problems to request available AI diagnosis for a failed build. Copy error for AI includes deployment context when available. Review the diagnosis before changing code; share sanitized logs with your developer or support if needed.

## Automatic deployment after a push
https://devoracloud.com/docs/push?lang=en

A push to the configured repository branch triggers deployment when automatic deployment is enabled. Check the selected branch, including repositories using master rather than main.
Follow the deployment status and test the resulting application URL. Read the failed deployment log before retrying unchanged code.

## What happens when you deploy
https://devoracloud.com/docs/funcionamento?lang=en

Devora reads repository metadata to suggest configuration. The execution engine clones the source with its access credential, builds and stores an image, then deploys containers with variables, resource limits and replica count.
The application subdomain is connected and HTTPS is checked. Build success alone is not proof that the application responds. Follow the deployment result and runtime logs. The application must run migrations and keep persistent data outside disposable container files.

## Builder, Dockerfile and port
https://devoracloud.com/docs/construtor?lang=en

Open Project settings → Build and deployment → Builder. Choose automatic Nixpacks, Dockerfile or static site. The same configuration remains accessible in Resources. For Dockerfile, provide its repository-relative path; monorepos often need a path such as apps/web/Dockerfile.
Set the application port under Network and health check → App port. It must match the port your process listens on, on 0.0.0.0. Save the configuration and publish again to apply it; saving does not replace the running app by itself.

## Platform API
https://devoracloud.com/docs/api?lang=en

The API base is https://api.devoracloud.com/v1. Create a scoped API key in the account tools and send Authorization: Bearer YOUR_KEY. A key belongs to one organization and gives access only to it. A key cannot create another key: POST /v1/api-keys called with a key returns 403 FORBIDDEN; only a logged-in person creates keys, in the dashboard. Never expose a secret API key to browser code.
Requests are limited by organization membership, key permissions and plan capacity. PLAN_LIMIT_EXCEEDED (HTTP 402) requires reducing reserved resources or upgrading; details carries resource, limit and used. With resource "subscription" the trial ended or an invoice is unpaid. POST /v1/projects/:id/scale accepts up to the plan ceiling (the failover standby is included and stays off); extra copies for autoscaling or load balancing are billed hourly up to the plan ceiling (Hobby 2, Pro 3, Enterprise 5) and need a paid plan in good standing; during the trial or with an unpaid invoice the API answers 402. Blindly retrying does not increase capacity.

## Notifications and integrations
https://devoracloud.com/docs/webhooks?lang=en

Configure your HTTPS receiver in the account Webhooks tools. Handle repeated events idempotently and consult the current resource state before important actions.
Payment-provider webhooks are internal to Devora. Customers do not need to configure a webhook in their application to activate their hosting plan.

## Primary region and replica destinations
https://devoracloud.com/docs/localizacao?lang=en

The primary and every copy must run on distinct physical machines, even within the same country. Two server entries or two virtual machines on one host do not protect against that host failing. Without enough independent destinations, distribution must remain pending and must never be shown as protected.
In your project, open Settings → Scaling → Project location. The screen separates the running primary from your preferred region and displays each destination’s status. Coming-soon and maintenance regions cannot be selected.
The plan total includes the primary and every additional copy. Each replica uses the same CPU and memory limits on another machine; adding replicas does not increase an individual instance’s power. Autoscaling is selectable only when included in the plan.
Saving records a preference, not a migration: the running project is not moved right away. If the primary server fails, a watcher starts the failover replica in the other region (USA ↔ Germany) within seconds, with nothing for you to do. Brazil is not offered as a place to run apps because it is CDN cache only.
Failure protection, load balancing and autoscaling are different goals. Recovery depends on healthy copies, traffic entry points and available data services. Applications need shared sessions, S3 files and coordinated jobs; application replicas do not automatically replicate the database.

## CPU, memory and resource reviews
https://devoracloud.com/docs/recursos?lang=en

The dashboard shows the percentage of the application quota, not total server usage. For a 0.5 vCPU application, 100% means that quota is occupied; it does not mean the entire machine is at capacity.
The red card and notification bell display CPU and memory warnings. A warning requires at least three minutes above 85% with fresh, continuous samples. At 100%, it becomes critical. Old or missing data is not presented as zero usage.
The warning remains while the condition is active and disappears after recovery. Charts use measured history when available. More traffic, demanding jobs or code issues can cause high usage; check logs before purchasing resources.
Review resources opens settings. View plans opens billing. The warning does not activate replicas, change CPU/RAM or confirm a purchase. Hourly add-ons are being prepared and are not billed automatically in this version.
CPU, memory, local storage and S3 are separate resources. Store images and videos in S3; application-local disk is not shared between replicas. The actual collector frequency determines how often readings change.

## Prepare your application
https://devoracloud.com/docs/preparar?lang=en

1. Read the port from process.env.PORT: Do not hard-code the port. Listen on 0.0.0.0, never on localhost. If ignored: The router delivers traffic to the declared port and nobody answers. Visitors get a 502 while the container is healthy.
2. Run migrations at startup, not during the build: Run migrate deploy before starting the server. There is no database to connect to while the image is being built. If ignored: The database ends up with zero tables and the app errors on the first query. This was the most common failure in real migrations.
3. Fail loudly when a migration fails: If migrate fails, the process must exit with the message in the log — not start anyway. If ignored: The app stays online serving errors, the dashboard shows green, and nobody notices until a customer complains.
4. NEXT_PUBLIC_* variables are build arguments: In Next.js they are written into the bundle during the build. Declare each one as ARG and promote it to ENV before the build line. If ignored: The development value is baked in forever. The production site keeps calling localhost.
5. Nothing important on the container disk: Uploads, images, attachments: send them to S3 storage. The container disk is wiped when the copy is recreated. If ignored: Files disappear on the next deploy, with no warning and no way to recover them.
6. Do not keep state only in process memory: Sessions, queues, shared cache: put them in the database or Redis. With more than one copy, each process has its own memory. If ignored: Users lose their session whenever a request lands on another copy, and writes vanish without any error.
7. A built-in scheduler needs a single copy: If the app has an internal cron, tell whoever deploys it. The alternative is to move the job to its own service. If ignored: Double charges, messages sent twice, customers blocked by mistake.
8. Answer something on /: Any response below 500 works — including a redirect to the login page. That is how the platform knows the app is alive. If ignored: The app is considered down and the owner gets an outage alert for an outage that does not exist.
9. Log to stdout, not to a file: Write to standard output. Do not open a log file inside the container. If ignored: The log is stuck on a disk nobody can reach, exactly when you need it.
10. Every secret comes from the environment: API keys, token secrets, third-party credentials: only from environment variables. Never committed, never with a default value that works. If ignored: The secret leaks in the repository and works for anyone who clones the code.
11. Monorepo: one service per program, in the same project: A site and an API from the same repository become two services of the same project, each with its own Dockerfile and port. Do not create two projects. If ignored: With two projects, secrets must be copied by hand from one to the other — and the day one changes and the other does not, the token stops being accepted and nobody knows why.
12. Dockerfile: give the path, keep the context at the root: In a monorepo, enter the full path of the service’s Dockerfile. The context stays at the root so the shared lockfile is found. If ignored: The build dies with "open Dockerfile: no such file or directory" in a repository that has a Dockerfile.

## Current limitations
https://devoracloud.com/docs/limites?lang=en

- Automatic backups for MySQL, MariaDB and MongoDB. Only PostgreSQL has them (and only on plans with backup). For the others, turn on the database’s external access and create the dump from your machine.
- SQL terminal and database password change. You can see the credentials but not change them in the dashboard.
- Scheduled tasks (cron) per project. If your app has a scheduled job, it must live inside the app — and then the app must run with a single copy, or the job runs twice.
- A volume mounted on more than one service of the same project. The volume goes to the primary service; mounting the same volume on two services on different cluster machines does not work.
- Deleting the data inside a volume from the dashboard. Removing the volume undoes the mount; the content stays on the cluster.
- Choosing a TLS certificate by hand. Certificates are issued and renewed by the platform; paths per domain are set in the address configuration.
- Disk metrics per project and request counts per domain. CPU, memory and RX/TX network traffic per project are available in the inspector.
- Infrastructure alerts by email. An application outage sends an email; a disk filling up does not yet.