> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Como hospedar uma API Express.js na Vertra Cloud

> Faça deploy de uma API Express.js na Vertra Cloud: escute em 0.0.0.0 e na variável PORT, publique o subdomínio e acompanhe as requisições nos logs ao vivo.

## Requisitos

* Node.js instalado localmente
* Conta na [Vertra Cloud](https://vertracloud.app)

## Estrutura do projeto

```
my-api/
├── src/
│   ├── index.js
│   ├── routes/
│   │   └── users.js
│   └── middleware/
│       └── auth.js
├── package.json
└── vertracloud.config
```

## Configuração

### package.json

```json theme={null}
{
  "name": "my-api",
  "version": "1.0.0",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js"
  },
  "dependencies": {
    "express": "^4.18.0",
    "cors": "^2.8.5",
    "dotenv": "^16.3.0"
  }
}
```

### vertracloud.config

```ini theme={null}
MAIN=src/index.js
START=npm start
VERSION=recommended
```

## Exemplo completo

```javascript theme={null}
const express = require('express');
const cors = require('cors');

const app = express();
const port = process.env.PORT || 80;

app.use(cors());
app.use(express.json());

app.get('/', (req, res) => {
  res.json({ message: 'API online on Vertra Cloud' });
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy', uptime: process.uptime() });
});

app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(port, '0.0.0.0', () => {
  console.log(`API running on port ${port}`);
});
```

> [!WARNING]
>
> Sempre use `'0.0.0.0'` como host em `app.listen()`. O bind padrão em `localhost` não aceita conexões externas dentro do container.

## Deploy

**Dashboard**

1. Compacte o projeto em um `.zip` (pastas como `node_modules`, `venv` e `target` são removidas automaticamente) ou envie-o ao GitHub.
2. No dashboard, clique em **Novo Projeto** e envie o `.zip` ou cole a URL do repositório.
3. Em **Build**, confira o runtime (**JavaScript**), o arquivo principal (`index.js`) e a memória. Os comandos de start e build ficam em **Configurações avançadas**.
4. Adicione suas variáveis de ambiente em **Variáveis de Ambiente**.
5. Em **Rede**, ative a **publicação na web** para que a aplicação receba um endereço `*.vertraweb.app` (plano Pro ou superior, 512 MB de memória). A aplicação precisa escutar na porta 80.
6. Revise e faça o deploy. Acompanhe a saída na aba **Logs**.

**CLI**

```bash theme={null}
vertra upload
vertra logs -f
```

Veja a [CLI](https://docs.vertracloud.app/pt-br/cli.md) para instalação e login.

**VS Code**

Abra a pasta com a extensão da Vertra Cloud instalada e execute **Deploy current project**. Veja a [extensão do VS Code](https://docs.vertracloud.app/pt-br/vscode-extension.md).

O passo a passo completo está em [Primeiro deploy](https://docs.vertracloud.app/pt-br/how-to-host.md).

## Versões disponíveis

| Versão | Status | Descrição |
| - | - | - |
| 24.22.1 | Mais recente | Node.js 24.22.1 (versão mais recente) |
| 22.23.4 | Recomendada | Node.js 22.23.4 LTS (recomendada para produção) |

## Conectando a um banco de dados

Os bancos da Vertra Cloud exigem TLS **e** o certificado de cliente. Coloque os três arquivos da aba
**Certificados** do banco no seu projeto e leia-os ao abrir o pool:

```javascript theme={null}
const fs = require('fs');
const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT), // única por banco, copie-a do dashboard
  user: 'postgres',
  password: process.env.DB_PASSWORD,
  database: 'postgres',
  ssl: {
    ca: fs.readFileSync('certificate.pem'),
    cert: fs.readFileSync('certificate.crt'),
    key: fs.readFileSync('certificate.key'),
    rejectUnauthorized: true,
  },
});
```

Os exemplos de MongoDB, Redis e MySQL estão em [Como me conecto a cada motor?](https://docs.vertracloud.app/pt-br/databases.md#como-me-conecto-a-cada-motor).

## Observações

* Para aplicações **TypeScript**, compile antes do deploy e aponte `MAIN` para o arquivo `.js` compilado
* Use **variáveis de ambiente** para a configuração do banco e para segredos
* O **reinício automático** vem ativado por padrão em todas as aplicações
* Configure um endpoint `/health` para monitoramento


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.