snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/pt/developers/self-host/capabilities/docker-compose.mdx

@@ -0,0 +1,262 @@
+---
+title: Docker Compose
+icon: docker
+---
+
+<Warning>
+Os contêineres Docker são para hospedagem em produção ou auto-hospedagem. Para contribuir, consulte a [Configuração local](/l/pt/developers/contribute/capabilities/local-setup).
+</Warning>
+
+## Visão geral
+
+Este guia fornece instruções passo a passo para instalar e configurar o aplicativo Twenty usando Docker Compose. O objetivo é tornar o processo simples e evitar armadilhas comuns que possam quebrar sua configuração.
+
+**Importante:** Modifique apenas as configurações explicitamente mencionadas neste guia. Alterar outras configurações pode levar a problemas.
+
+Consulte [Configurar Variáveis de Ambiente](/l/pt/developers/self-host/capabilities/setup) para configuração avançada. Todas as variáveis de ambiente devem ser declaradas no arquivo `docker-compose.yml` no nível do servidor e/ou do trabalhador, dependendo da variável.
+
+## Requisitos do Sistema
+
+* RAM: Certifique-se de que seu ambiente tenha pelo menos 2GB de RAM. Memória insuficiente pode causar falhas nos processos.
+* Docker & Docker Compose: Certifique-se de que ambos estão instalados e atualizados.
+
+## Opção 1: Script de uma linha
+
+Instale a versão estável mais recente do Twenty com um único comando:
+
+```bash
+bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+Para instalar uma versão ou branch específica:
+
+```bash
+VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)
+```
+
+* Substitua x.y.z pelo número da versão desejada.
+* Substitua branch-name pelo nome da branch que você deseja instalar.
+
+## Opção 2: Etapas manuais
+
+Siga estas etapas para uma configuração manual.
+
+### Etapa 1: Configure o arquivo de ambiente
+
+1. **Crie o arquivo .env**
+
+   Copie o exemplo de arquivo de ambiente para um novo arquivo .env no seu diretório de trabalho:
+
+   ```bash
+   curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example
+   ```
+
+2. **Gerar uma chave de criptografia**
+
+   Execute o seguinte comando para gerar uma string aleatória única:
+
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   **Importante:** Mantenha este valor em segredo / não o compartilhe. Perder `ENCRYPTION_KEY` significa perder o acesso a todos os segredos armazenados no banco de dados (tokens OAuth, variáveis de aplicação, segredos TOTP, etc.).
+
+3. **Atualize o `.env`**
+
+   Substitua o valor do espaço reservado no seu arquivo .env pelo token gerado:
+
+   ```ini
+   ENCRYPTION_KEY=random_string
+   ```
+
+   Consulte o [guia de rotação de chaves](/l/pt/developers/self-host/capabilities/key-rotation) para obter instruções sobre como fazer a rotação sem tempo de inatividade.
+
+4. **Defina a Senha do Postgres**
+
+   Atualize o valor `PG_DATABASE_PASSWORD` no arquivo .env com uma senha forte sem caracteres especiais.
+
+   ```ini
+   PG_DATABASE_PASSWORD=my_strong_password
+   ```
+
+### Etapa 2: Obtenha o arquivo Docker Compose
+
+Baixe o arquivo `docker-compose.yml` para o seu diretório de trabalho:
+
+```bash
+curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml
+```
+
+### Etapa 3: Inicie o Aplicativo
+
+Inicie os contêineres Docker:
+
+```bash
+docker compose up -d
+```
+
+### Etapa 4: Acesse o Aplicativo
+
+Se você hospedar o twentyCRM no seu próprio computador, abra o navegador e acesse [http://localhost:3000](http://localhost:3000).
+
+Se você hospedar em um servidor, verifique se o servidor está em execução e se está tudo ok com
+
+```bash
+curl http://localhost:3000
+```
+
+## Configuração
+
+### Expor o Twenty para Acesso Externo
+
+Por padrão, o Twenty é executado em `localhost` na porta `3000`. A interface acessa a API a partir da origem do próprio navegador, portanto pode ser carregada de qualquer nome de host que alcance o contêiner — ainda assim, defina `SERVER_URL` como sua URL pública: o servidor a utiliza para gerar links (e-mails, callbacks de OAuth) e para detectar HTTPS e definir cookies seguros.
+
+#### Compreendendo `SERVER_URL`
+
+* **Protocolo:** Use `http` ou `https` dependendo da sua configuração.
+  * Use `http` se você não configurou SSL.
+  * Use `https` se você tiver SSL configurado.
+* **Domínio/IP:** Este é o nome de domínio ou endereço IP onde seu aplicativo está acessível.
+* **Porta:** Inclua o número da porta se você não estiver usando as portas padrão (`80` para `http`, `443` para `https`).
+
+### Requisitos de SSL
+
+SSL (HTTPS) é necessário para que certos recursos do navegador funcionem corretamente. Embora esses recursos possam funcionar durante o desenvolvimento local (já que os navegadores tratam o localhost de modo diferente), é necessária uma configuração adequada de SSL ao hospedar o Twenty em um domínio normal.
+
+Por exemplo, a API da área de transferência pode exigir um contexto seguro - alguns recursos, como botões de cópia através do aplicativo, podem não funcionar sem HTTPS ativado.
+
+Recomendamos fortemente configurar o Twenty atrás de um proxy reverso com terminação SSL para segurança e funcionalidade ótimas.
+
+#### Configurando `SERVER_URL`
+
+1. **Determine sua URL de Acesso**
+   * **Sem Proxy Reverso (Acesso Direto):**
+
+     Se você estiver acessando o aplicativo diretamente sem um proxy reverso:
+
+     ```ini
+     SERVER_URL=http://your-domain-or-ip:3000
+     ```
+
+   * **Com Proxy Reverso (Portas Padrão):**
+
+     Se você estiver usando um proxy reverso como Nginx ou Traefik e tiver SSL configurado:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip
+     ```
+
+   * **Com Proxy Reverso (Portas Customizadas):**
+
+     Se você estiver usando portas não-padrão:
+
+     ```ini
+     SERVER_URL=https://your-domain-or-ip:custom-port
+     ```
+
+2. **Atualize o arquivo `.env`**
+
+   Abra seu arquivo `.env` e atualize o `SERVER_URL`:
+
+   ```ini
+   SERVER_URL=http(s)://your-domain-or-ip:your-port
+   ```
+
+   **Exemplos:**
+
+   * Acesso direto sem SSL:
+     ```ini
+     SERVER_URL=http://123.45.67.89:3000
+     ```
+   * Acesso via domínio com SSL:
+     ```ini
+     SERVER_URL=https://mytwentyapp.com
+     ```
+
+3. **Reinicie o Aplicativo**
+
+   Para que as alterações entrem em vigor, reinicie os contêineres Docker:
+
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+#### Considerações
+
+* **Configuração de Proxy Reverso:**
+
+  Certifique-se de que seu proxy reverso encaminha as solicitações para a porta interna correta (`3000` por padrão). Configure a terminação SSL e quaisquer cabeçalhos necessários.
+
+* **Configurações de Firewall:**
+
+  Abra as portas necessárias no seu firewall para permitir acesso externo.
+
+* **Consistência:**
+
+  A `SERVER_URL` deve corresponder à forma como os usuários acessam seu aplicativo nos navegadores.
+
+#### Persistência
+
+* **Volumes de Dados:**
+
+  A configuração do Docker Compose usa volumes para persistir dados para o banco de dados e armazenamento do servidor.
+
+* **Ambientes Sem Estado:**
+
+  Se estiver implantando em um ambiente sem estado (por exemplo, certos serviços de nuvem), configure armazenamento externo para persistir dados.
+
+## Backup e restauração
+
+Backups regulares protegem os dados do seu CRM contra perda.
+
+### Crie um backup do banco de dados
+
+```bash
+docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql
+```
+
+### Automatize backups diários
+
+Adicione ao seu crontab (`crontab -e`):
+
+```bash
+0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql
+```
+
+### Restaurar a partir de um backup
+
+1. Pare o aplicativo:
+
+```bash
+docker compose stop server worker
+```
+
+2. Restaure o banco de dados:
+
+```bash
+docker exec -i twenty-postgres psql -U postgres twenty < backup_20240115.sql
+```
+
+3. Reinicie os serviços:
+
+```bash
+docker compose up -d
+```
+
+### Melhores práticas de backup
+
+* **Teste as restaurações regularmente** — verifique se os backups realmente funcionam
+* **Armazene os backups fora das instalações** — use armazenamento em nuvem (S3, GCS, etc.)
+* **Criptografe dados confidenciais** — proteja os backups com criptografia
+* **Mantenha várias cópias** — guarde backups diários, semanais e mensais
+
+## Resolução de Problemas
+
+Se encontrar algum problema, verifique [Resolução de Problemas](/l/pt/developers/self-host/capabilities/troubleshooting) para soluções.
+
+## Hospedagem Gerenciada
+
+<Tip>
+  Prefere não executar e manter o Twenty você mesmo? [Encontre um parceiro Twenty certificado de hospedagem](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-docker-compose) para implantar, hospedar e gerir a sua instância de ponta a ponta. *(Ou entre em contato com a nossa equipe: [contact@twenty.com](mailto:contact@twenty.com).)*
+</Tip>

packages/twenty-docs/l/pt/developers/self-host/capabilities/key-rotation.mdx

@@ -0,0 +1,60 @@
+---
+title: Rotação de chaves
+icon: rotate
+---
+
+Twenty possui duas famílias de chaves independentes:
+
+* **Chaves de assinatura JWT** — pares de chaves assimétricas ES256 (com `kid`) armazenados em `core."signingKey"`, usados para assinar e verificar tokens de acesso/atualização.
+* **Chave de criptografia em repouso** — `ENCRYPTION_KEY`, usada para criptografar tokens OAuth, variáveis de aplicação, chaves privadas de chaves de assinatura, valores confidenciais de configuração e segredos TOTP dentro de um envelope `enc:v2:`.
+
+`APP_SECRET` é um segredo legado mantido para compatibilidade retroativa: quando `ENCRYPTION_KEY` não está definido, ele funciona como fallback de criptografia em repouso / cookie de sessão e ainda verifica tokens de acesso HS256 já existentes. Ele será descontinuado.
+
+## Chaves de assinatura JWT
+
+Cada chave carrega uma `publicKey` (mantida indefinidamente para que possa verificar tokens emitidos anteriormente), uma `privateKey` criptografada (usada apenas enquanto a chave é atual), um sinalizador `isCurrent` (exatamente uma linha por vez) e um `revokedAt` opcional.
+
+### Rotacionar a chave atual
+
+Defina `SIGNING_KEY_ROTATION_DAYS` para ativar: um cron diário então gera uma nova chave e a define como atual quando a existente for mais antiga do que esse limite. Chaves anteriores *não* são revogadas, então tokens assinados sob elas continuam sendo verificados. Deixe a variável não definida para desativar a rotação automática.
+
+<Note>A rotação automática está disponível a partir da v2.6+.</Note>
+
+### Revogar uma chave (apenas vazamento / emergência)
+
+**Settings → Admin Panel → Signing keys → Revoke** em uma linha que não seja a atual. Apaga o material privado criptografado, define `revokedAt` e rejeita todos os tokens existentes assinados sob aquele `kid`.
+
+## Rotacionar `ENCRYPTION_KEY`
+
+<Note>O comando `secret-encryption:rotate` descrito abaixo é disponibilizado a partir da v2.6+.</Note>
+
+Cada valor criptografado é encapsulado como `enc:v2:\<keyId>:\<payload>`, em que `\<keyId>` é um prefixo hexadecimal de 8 caracteres derivado da chave bruta. A rotação é online e retomável.
+
+1. **Gerar uma nova chave**: `openssl rand -base64 32`.
+
+2. **Configurar ambas as chaves lado a lado** em `.env`, depois reinicie:
+   ```ini
+   ENCRYPTION_KEY=NEW_VALUE
+   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
+   ```
+   Novas gravações usam a nova chave; linhas existentes ainda são descriptografadas por meio do fallback.
+
+3. **Recriptografar linhas existentes**:
+
+   ```bash
+   docker exec -it {server_container} yarn command:prod secret-encryption:rotate
+   ```
+
+   O comando percorre seis sites (`connected-account-tokens`, `application-variable`, `application-registration-variable`, `signing-key-private-keys`, `sensitive-config-storage`, `totp-secrets`). Um filtro SQL ignora as linhas que já estão no novo `\<keyId>`, portanto o comando é idempotente: interrompa e execute novamente conforme necessário. Sai com código diferente de zero se alguma linha falhar — execute novamente para tentar de novo.
+
+   | Opção                                    | Descrição                                                      |
+   | ---------------------------------------- | -------------------------------------------------------------- |
+   | `-s, --site \<site>`    | Limitar a um único site.                                       |
+   | `-b, --batch-size \<n>` | Linhas por lote (padrão `200`, máximo `5000`).                 |
+   | `-d, --dry-run`                          | Descriptografar + recriptografar em memória, pular o `UPDATE`. |
+
+4. **Remova o fallback** assim que `--dry-run` mostrar zero linhas restantes: remova `FALLBACK_ENCRYPTION_KEY` e reinicie.
+
+## Suporte legado a `APP_SECRET`
+
+Instâncias antigas que nunca definiram `ENCRYPTION_KEY` usam `APP_SECRET` como chave de criptografia em repouso (e como segredo de cookie de sessão, derivado dela). Esse caminho é mantido para compatibilidade retroativa, mas está **descontinuado** — defina uma `ENCRYPTION_KEY` dedicada e siga o procedimento de rotação acima para migrar para fora dele. O próprio `APP_SECRET` continua em uso para verificar tokens de acesso HS256 legados.

packages/twenty-docs/l/pt/developers/self-host/capabilities/setup.mdx

@@ -0,0 +1,415 @@
+---
+title: Configuração
+icon: gear
+---
+
+# Gestão de Configuração
+
+<Warning>
+**Primeira vez instalando?** Siga o [guia de instalação do Docker Compose](/l/pt/developers/self-host/capabilities/docker-compose) para iniciar o Twenty, depois retorne aqui para configurar.
+</Warning>
+
+Twenty oferece **dois modos de configuração** para atender diferentes necessidades de implantação:
+
+**Acesso ao painel de administração:** Apenas usuários com privilégios de administrador (`canAccessFullAdminPanel: true`) podem acessar a interface de configuração.
+
+## 1. Configuração do Painel Administrativo (Padrão)
+
+```bash
+IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default
+```
+
+**A maior parte da configuração acontece através da interface do usuário** após a instalação:
+
+1. Acesse sua instância do Twenty (geralmente `http://localhost:3000`)
+2. Vá para **Configurações / Painel de Administração / Variáveis de Configuração**
+3. Configure integrações, email, armazenamento e mais
+4. As alterações entram em vigor imediatamente (em até 15 segundos para implantações em múltiplos containers)
+
+<Warning>
+**Implantações em Múltiplos Containers:** Ao usar a configuração do banco de dados (`IS_CONFIG_VARIABLES_IN_DB_ENABLED=true`), tanto servidores quanto containers de trabalho leem do mesmo banco de dados. Alterações no painel de administração afetam ambos automaticamente, eliminando a necessidade de duplicar variáveis de ambiente entre os containers (exceto para variáveis de infraestrutura).
+</Warning>
+
+**O que você pode configurar através do painel de administração:**
+
+* **Autenticação** - OAuth do Google/Microsoft, configurações de senha
+* **Email** - configurações SMTP, modelos, verificação
+* **Armazenamento** - configuração S3, caminhos de armazenamento local
+* **Integrações** - Gmail, Google Calendar, serviços Microsoft
+* **Fluxo de trabalho e limitação de taxa** - limites de execução, limitação de taxa da API
+* **E muito mais...**
+
+![Variáveis de configuração do painel de administração](/images/user-guide/setup/admin-panel-config-variables.png)
+
+<Warning>
+Cada variável é documentada com descrições no seu painel de administração em **Configurações → Painel de Administração → Variáveis de Configuração**.
+Algumas configurações de infraestrutura como conexões de banco de dados (`PG_DATABASE_URL`), URLs de servidor (`SERVER_URL`) e segredos (`ENCRYPTION_KEY`, `FALLBACK_ENCRYPTION_KEY`) só podem ser configuradas via arquivo `.env`.
+
+[Referência técnica completa →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts)
+</Warning>
+
+## Chaves de criptografia
+
+A Twenty usa duas chaves de criptografia definidas apenas por variáveis de ambiente:
+
+| Variável                  | Finalidade                                                                                                                                                                           | Obrigatório                                                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `ENCRYPTION_KEY`          | Chave primária usada para criptografar segredos em repouso (tokens OAuth, variáveis do aplicativo, chaves privadas de assinatura, segredos TOTP, valores de configuração sensíveis). | Sim para novas instalações (instalações legadas podem, em vez disso, depender de `APP_SECRET` — veja abaixo) |
+| `FALLBACK_ENCRYPTION_KEY` | Chave somente para verificação. Definida durante uma rotação para a *chave `ENCRYPTION_KEY` anterior* para que as linhas existentes permaneçam descriptografáveis.                   | Apenas durante a rotação                                                                                     |
+
+Para compatibilidade retroativa, se `ENCRYPTION_KEY` não estiver definida, Twenty recorre a `APP_SECRET` para criptografia em repouso — correspondendo ao comportamento legado de implantações mais antigas. Novas instalações devem sempre definir uma `ENCRYPTION_KEY` dedicada.
+
+Gere valores com `openssl rand -base64 32` e armazene-os em um local seguro (um gerenciador de segredos, configuração selada, etc.). Perder a `ENCRYPTION_KEY` significa perder o acesso a todos os segredos armazenados no banco de dados.
+
+Para rotacionar a `ENCRYPTION_KEY` sem tempo de inatividade, consulte o [guia de rotação de chaves](/l/pt/developers/self-host/capabilities/key-rotation).
+
+## 2. Configuração Somente por Ambiente
+
+```bash
+IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
+```
+
+**Toda a configuração gerenciada através de arquivos `.env`:**
+
+1. Defina `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` no seu arquivo `.env`
+2. Adicione todas as variáveis de configuração ao seu arquivo `.env`
+3. Reinicie os containers para que as alterações entrem em vigor
+4. O painel de administração mostrará valores atuais, mas não poderá modificá-los
+
+## Modo de vários espaços de trabalho
+
+Por padrão, o Twenty é executado no **modo de espaço de trabalho único** — ideal para a maioria das implantações auto-hospedadas em que você precisa de uma instância de CRM para sua organização.
+
+### Modo de espaço de trabalho único (padrão)
+
+```bash
+IS_MULTIWORKSPACE_ENABLED=false  # default
+```
+
+* Um espaço de trabalho por instância do Twenty
+* O primeiro usuário torna-se automaticamente administrador com privilégios completos (`canImpersonate` e `canAccessFullAdminPanel`)
+* Novos cadastros são desativados após a criação do primeiro espaço de trabalho
+* Estrutura de URL simples: `https://your-domain.com`
+
+### Ativando o modo de vários espaços de trabalho
+
+```bash
+IS_MULTIWORKSPACE_ENABLED=true
+DEFAULT_SUBDOMAIN=app  # default value
+```
+
+Ative o modo de vários espaços de trabalho para implantações ao estilo SaaS em que várias equipes independentes precisam de seus próprios espaços de trabalho na mesma instância do Twenty.
+
+**Principais diferenças em relação ao modo de espaço de trabalho único:**
+
+* Vários espaços de trabalho podem ser criados na mesma instância
+* Cada espaço de trabalho recebe seu próprio subdomínio (por exemplo, `sales.your-domain.com`, `marketing.your-domain.com`)
+* Os usuários se cadastram e fazem login em `{DEFAULT_SUBDOMAIN}.your-domain.com` (por exemplo, `app.your-domain.com`)
+* Sem privilégios administrativos automáticos — o primeiro usuário de cada espaço de trabalho é um usuário comum
+* Configurações específicas do espaço de trabalho, como subdomínio e domínio personalizado, ficam disponíveis nas configurações do espaço de trabalho
+
+<Warning>
+**Configuração apenas por ambiente:** `IS_MULTIWORKSPACE_ENABLED` só pode ser configurado via arquivo `.env` e requer reinicialização. Isso não pode ser alterado pelo painel de administração.
+</Warning>
+
+### Configuração de DNS para vários espaços de trabalho
+
+Ao usar o modo de vários espaços de trabalho, configure seu DNS com um registro curinga para permitir a criação dinâmica de subdomínios:
+
+```
+*.your-domain.com -> your-server-ip
+```
+
+Isso permite o roteamento automático de subdomínios para novos espaços de trabalho sem configuração manual de DNS.
+
+### Restringindo a criação de espaços de trabalho
+
+No modo de vários espaços de trabalho, você pode querer limitar quem pode criar novos espaços de trabalho:
+
+```bash
+IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
+```
+
+Quando ativado, apenas usuários com `canAccessFullAdminPanel` podem criar espaços de trabalho adicionais. Os usuários ainda podem criar seu primeiro espaço de trabalho durante o cadastro inicial.
+
+## Integração com Gmail e Google Calendar
+
+### Criar Projeto no Google Cloud
+
+1. Vá para [Google Cloud Console](https://console.cloud.google.com/)
+2. Crie um novo projeto ou selecione um já existente
+3. Ative essas APIs:
+
+* [API do Gmail](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
+* [API do Google Calendar](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
+* [API de Pessoas](https://console.cloud.google.com/apis/library/people.googleapis.com)
+
+### Configure OAuth
+
+1. Vá para [Credenciais](https://console.cloud.google.com/apis/credentials)
+2. Crie um ID do Cliente OAuth 2.0
+3. Adicione estes URIs de redirecionamento:
+   * `https://{your-domain}/auth/google/redirect` (para SSO)
+   * `https://{your-domain}/auth/google-apis/get-access-token` (para integrações)
+
+### Configurar no Twenty
+
+1. Vá para **Configurações → Painel de Administração → Variáveis de Configuração**
+2. Encontre a seção **Google Auth**
+3. Defina estas variáveis:
+   * `MESSAGING_PROVIDER_GMAIL_ENABLED=true`
+   * `CALENDAR_PROVIDER_GOOGLE_ENABLED=true`
+   * `AUTH_GOOGLE_CLIENT_ID={client-id}`
+   * `AUTH_GOOGLE_CLIENT_SECRET={client-secret}`
+   * `AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect`
+   * `AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token`
+
+<Warning>
+**Modo somente ambiente:** Se você definir `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, adicione estas variáveis ao seu arquivo `.env`.
+</Warning>
+
+**Escopos necessários** (configurados automaticamente):
+[Veja o código relevante](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-google-apis-oauth-scopes.ts#L4-L10)
+
+* `https://www.googleapis.com/auth/calendar.events`
+* `https://www.googleapis.com/auth/gmail.readonly`
+* `https://www.googleapis.com/auth/profile.emails.read`
+
+### Se seu aplicativo estiver em modo de teste
+
+Se seu aplicativo estiver em modo de teste, será necessário adicionar usuários de teste ao seu projeto.
+
+Na [tela de consentimento OAuth](https://console.cloud.google.com/apis/credentials/consent), adicione seus usuários de teste à seção "Usuários de teste".
+
+## Integração com Microsoft 365
+
+<Warning>
+Os usuários devem ter uma [Licença do Microsoft 365](https://admin.microsoft.com/Adminportal/Home) para poder usar as APIs de Calendário e Mensagem. Eles não poderão sincronizar sua conta no Twenty sem uma.
+</Warning>
+
+### Criar um projeto no Microsoft Azure
+
+Você precisará criar um projeto no [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) e obter as credenciais.
+
+### Habilitar APIs
+
+No Console do Microsoft Azure habilite as seguintes APIs em "Permissões":
+
+* Microsoft Graph: Mail.ReadWrite
+* Microsoft Graph: Mail.Send
+* Microsoft Graph: Calendars.Read
+* Microsoft Graph: User.Read
+* Microsoft Graph: openid
+* Microsoft Graph: email
+* Microsoft Graph: profile
+* Microsoft Graph: offline_access
+
+<Note>
+"Mail.ReadWrite" e "Mail.Send" são obrigatórios apenas se você quiser enviar emails usando nossas ações de fluxo de trabalho. Você pode usar "Mail.Read" em vez disso se quiser apenas receber emails.
+</Note>
+
+<Note>
+"Calendars.ReadWrite" é obrigatório se você quiser criar eventos de calendário usando nossas ações de fluxo de trabalho. Se você quiser apenas sincronizar eventos de calendário, use "Calendars.Read".
+</Note>
+
+### URIs de redirecionamento autorizados
+
+Você precisa adicionar os seguintes URIs de redirecionamento ao seu projeto:
+
+* `https://{your-domain}/auth/microsoft/redirect` se você quiser usar SSO da Microsoft
+* `https://{your-domain}/auth/microsoft-apis/get-access-token`
+
+### Configurar no Twenty
+
+1. Vá para **Configurações → Painel de Administração → Variáveis de Configuração**
+2. Encontre a seção **Microsoft Auth**
+3. Defina estas variáveis:
+   * `MESSAGING_PROVIDER_MICROSOFT_ENABLED=true`
+   * `CALENDAR_PROVIDER_MICROSOFT_ENABLED=true`
+   * `AUTH_MICROSOFT_ENABLED=true`
+   * `AUTH_MICROSOFT_CLIENT_ID={client-id}`
+   * `AUTH_MICROSOFT_CLIENT_SECRET={client-secret}`
+   * `AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirect`
+   * `AUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token`
+
+<Warning>
+**Modo somente ambiente:** Se você definir `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, adicione estas variáveis ao seu arquivo `.env`.
+</Warning>
+
+### Configurar escopos
+
+[Veja o código relevante](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-microsoft-apis-oauth-scopes.ts#L2-L9)
+
+* 'openid'
+* 'email'
+* 'perfil'
+* 'offline_access'
+* 'Mail.ReadWrite'
+* 'Mail.Send'
+* 'Calendars.Read'
+
+### Se seu aplicativo estiver em modo de teste
+
+Se seu aplicativo estiver em modo de teste, será necessário adicionar usuários de teste ao seu projeto.
+
+Adicione seus usuários de teste à seção "Usuários e grupos".
+
+## Trabalhos em Segundo Plano para Calendário e Mensagens
+
+Após configurar integrações com Gmail, Google Calendar ou Microsoft 365, é necessário iniciar os trabalhos em segundo plano que sincronizam dados.
+
+Registre os seguintes trabalhos recorrentes em seu container de trabalho:
+
+```bash
+# from your worker container
+yarn command:prod cron:messaging:messages-import
+yarn command:prod cron:messaging:message-list-fetch
+yarn command:prod cron:calendar:calendar-event-list-fetch
+yarn command:prod cron:calendar:calendar-events-import
+yarn command:prod cron:messaging:ongoing-stale
+yarn command:prod cron:calendar:ongoing-stale
+yarn command:prod cron:workflow:automated-cron-trigger
+```
+
+## Configuração de Email
+
+1. Vá para **Configurações → Painel de Administração → Variáveis de Configuração**
+2. Encontre a seção **Email**
+3. Configure suas configurações SMTP:
+
+<Tabs>
+
+  <Tab title="Gmail">
+
+  Você precisará provisionar uma [Senha de App](https://support.google.com/accounts/answer/185833).
+  * EMAIL_DRIVER=smtp
+  * EMAIL_SMTP_HOST=smtp.gmail.com
+  * EMAIL_SMTP_PORT=465
+  * EMAIL_SMTP_USER=gmail_email_address
+  * EMAIL_SMTP_PASSWORD='gmail_app_password'
+
+  </Tab>
+
+  <Tab title="Office365">
+
+  Lembre-se de que, se você tiver 2FA ativado, precisará providenciar uma [Senha de App](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9).
+  * EMAIL_DRIVER=smtp
+  * EMAIL_SMTP_HOST=smtp.office365.com
+  * EMAIL_SMTP_PORT=587
+  * EMAIL_SMTP_USER=office365_email_address
+  * EMAIL_SMTP_PASSWORD='office365_password'
+
+  </Tab>
+
+  <Tab title="smtp4dev">
+
+  **smtp4dev** é um servidor SMTP falso para desenvolvimento e teste.
+  * Execute a imagem smtp4dev: `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev`
+  * Acesse a interface smtp4dev aqui: [http://localhost:8090](http://localhost:8090)
+  * Defina as seguintes variáveis:
+    * EMAIL_DRIVER=smtp
+    * EMAIL_SMTP_HOST=localhost
+    * EMAIL_SMTP_PORT=2525
+
+  </Tab>
+
+</Tabs>
+
+<Warning>
+**Modo somente ambiente:** Se você definir `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, adicione estas variáveis ao seu arquivo `.env`.
+</Warning>
+
+## Armazenamento S3
+
+<Warning>
+Por padrão, o Twenty armazena os arquivos enviados no sistema de arquivos local. Para implantações em produção, use o S3 ou um serviço compatível com S3 (MinIO, DigitalOcean Spaces, etc.) para garantir que os arquivos persistam entre reinicializações do contêiner e possam escalar em várias instâncias de servidor.
+</Warning>
+
+Defina `STORAGE_TYPE=S_3` e configure as variáveis `STORAGE_S3_*` pelo painel de administração ou `.env`. Veja a [referência de config-variables.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) para a lista completa de variáveis do S3.
+
+Ao usar o S3 com recursos dependentes de CORS (por exemplo, downloads de arquivos no navegador), verifique se o seu bucket permite a origem do seu frontend do Twenty na sua configuração de CORS.
+
+## Funções lógicas e interpretador de código
+
+O Twenty oferece suporte a funções lógicas para fluxos de trabalho e ao interpretador de código para análise de dados com IA. Ambos executam código fornecido pelo usuário e exigem configuração explícita por motivos de segurança.
+
+### Padrões de segurança
+
+**Em produção (NODE_ENV=production):** Tanto as funções lógicas quanto o interpretador de código têm como padrão **Desativado**. Você deve habilitá-los explicitamente com `LOGIC_FUNCTION_TYPE` e `CODE_INTERPRETER_TYPE` se precisar desses recursos.
+
+**Em desenvolvimento (NODE_ENV=development):** Ambos têm como padrão **LOCAL** por conveniência ao executar localmente.
+
+<Warning>
+**Aviso de segurança:** O driver local (`LOGIC_FUNCTION_TYPE=LOCAL` ou `CODE_INTERPRETER_TYPE=LOCAL`) executa código diretamente no host em um processo Node.js sem sandbox. Deve ser usado apenas para código confiável em desenvolvimento. Para implantações de produção que lidam com código não confiável, use `LOGIC_FUNCTION_TYPE=LAMBDA` ou `CODE_INTERPRETER_TYPE=E2B` (com sandbox), ou mantenha-os desativados.
+</Warning>
+
+### Funções lógicas - Drivers disponíveis
+
+| Driver     | Variável de ambiente           | Caso de uso                                | Nível de segurança                     |
+| ---------- | ------------------------------ | ------------------------------------------ | -------------------------------------- |
+| Desativado | `LOGIC_FUNCTION_TYPE=DISABLED` | Desativar completamente as funções lógicas | N/A                                    |
+| Local      | `LOGIC_FUNCTION_TYPE=LOCAL`    | Desenvolvimento e ambientes confiáveis     | Baixo (sem sandbox)                    |
+| Lambda     | `LOGIC_FUNCTION_TYPE=LAMBDA`   | Produção com código não confiável          | Alto (isolamento em nível de hardware) |
+
+### Funções lógicas - Configuração recomendada
+
+**Para desenvolvimento:**
+
+```bash
+LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development
+```
+
+**Para produção (AWS):**
+
+```bash
+LOGIC_FUNCTION_TYPE=LAMBDA
+LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
+LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
+LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
+LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
+```
+
+**Para desativar as funções lógicas:**
+
+```bash
+LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production
+```
+
+### Interpretador de código - Drivers disponíveis
+
+| Driver     | Variável de ambiente             | Caso de uso                          | Nível de segurança     |
+| ---------- | -------------------------------- | ------------------------------------ | ---------------------- |
+| Desativado | `CODE_INTERPRETER_TYPE=DISABLED` | Desativar a execução de código de IA | N/A                    |
+| Local      | `CODE_INTERPRETER_TYPE=LOCAL`    | Apenas para desenvolvimento          | Baixo (sem sandbox)    |
+| E2B        | `CODE_INTERPRETER_TYPE=E_2_B`    | Produção com execução em sandbox     | Alto (sandbox isolado) |
+
+<Note>
+Ao usar `LOGIC_FUNCTION_TYPE=DISABLED` ou `CODE_INTERPRETER_TYPE=DISABLED`, qualquer tentativa de execução retornará um erro. Isso é útil se você quiser executar o Twenty sem esses recursos.
+</Note>
+
+## API e front-end em hosts separados
+
+Apenas relevante se você não permitir que o back-end sirva o front-end. Implantações de mesma origem
+não precisam de nada aqui.
+
+Declare todas as origens de navegador que se comunicam com a API, separadas por vírgula. `SERVER_URL`
+e `FRONTEND_URL` já são confiáveis. O servidor registra um aviso quando um navegador
+faz uma chamada a partir de uma origem não declarada.
+
+```bash
+AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com
+```
+
+<Warning>
+O front-end envia credenciais em todas as solicitações, e os navegadores rejeitam uma
+resposta com credenciais vinda de uma origem não declarada, portanto o app não carrega até
+que você defina isso.
+</Warning>
+
+Se os dois hosts estiverem em domínios registráveis diferentes (não apenas em
+subdomínios diferentes), também defina `AUTH_COOKIE_SAME_SITE=none`, o que requer HTTPS.
+
+Com o multi-workspace ativado, não liste aqui todos os subdomínios dos workspaces.
+Em vez disso, roteie os caminhos da API (`/graphql`, `/metadata`, `/rest`, `/auth/`,
+`/client-config`, `/file`) para o back-end em cada hostname de workspace, para que cada
+workspace permaneça na mesma origem — é assim que o Twenty Cloud funciona.

packages/twenty-docs/l/pt/developers/self-host/capabilities/troubleshooting.mdx

@@ -0,0 +1,254 @@
+---
+title: Resolução de Problemas
+icon: wrench
+---
+
+## Resolução de Problemas
+
+Se encontrar algum problema ao configurar o ambiente para desenvolvimento, atualizar sua instância ou auto-hospedagem, aqui estão algumas soluções para problemas comuns.
+
+### Auto-hospedagem
+
+#### Primeira instalação resulta em `falha na autenticação de senha para o usuário "postgres"`
+
+🚨 **IMPORTANTE: Esta solução é APENAS para instalações novas** 🚨
+Se você tiver uma instância existente do Twenty com dados em produção, **NÃO** siga estes passos, pois eles excluirão permanentemente seu banco de dados!
+
+Ao instalar o Twenty pela primeira vez, você pode querer alterar a senha padrão do banco de dados.
+A senha definida durante a primeira instalação é armazenada permanentemente no volume do banco de dados. Se posteriormente tentar alterar esta senha na sua configuração sem remover o volume antigo, receberá erros de autenticação porque o banco de dados ainda está usando a senha original.
+
+⚠️ AVISO: Seguir os próximos passos irá EXCLUIR PERMANENTEMENTE todos os dados do banco de dados! ⚠️
+Prossiga apenas se esta for uma instalação nova, sem dados importantes.
+
+Para atualizar o `PG_DATABASE_PASSWORD`, você precisa:
+
+```sh
+# Update the PG_DATABASE_PASSWORD in .env
+docker compose down --volumes
+docker compose up -d
+```
+
+#### Quebras de linha CR encontradas [Windows]
+
+Isto acontece devido a caracteres de final de linha do Windows combinados com sua configuração do Git. Tente executar:
+
+```
+git config --global core.autocrlf false
+```
+
+Depois exclua o repositório e clone novamente.
+
+#### Esquema de metadados ausente
+
+Durante a instalação do Twenty, é necessário configurar seu banco de dados postgres com os esquemas, extensões e usuários corretos.
+Se conseguir executar esta configuração, você deve ter os esquemas `default` e `metadata` no seu banco de dados.
+Se não, certifique-se de que você não tem mais de uma instância do PostgreSQL em execução no seu computador.
+
+#### Não é possível encontrar o módulo 'twenty-emails' ou suas declarações de tipo correspondentes.
+
+Você precisa construir o pacote `vinte e-mails` (`npx nx roda vinte e-mails:build`) antes de executar a inicialização do banco de dados.
+
+#### Pacote twenty-x ausente
+
+Certifique-se de executar o yarn no diretório raiz e depois executar `npx nx server:dev twenty-server`. Se isso ainda não funcionar, tente compilar manualmente o pacote ausente.
+
+#### Lint no Save não funcionando
+
+Isso deve funcionar automaticamente com a extensão Oxc (`oxc.oxc-vscode`) instalada. Se isto não funcionar, tente adicionar isso às suas configurações de VS Code (escopo de contêiner de desenvolvedor):
+
+```
+"editor.codeActionsOnSave": {
+
+  "source.fixAll.oxc": "explicit"
+
+}
+```
+
+#### Ao executar o `npx nx start` ou o `npx nx start twenty-front`, um erro de uso de memória é lançado
+
+Execute apenas os serviços que você precisa, ao invés do `npx nx start`. Por exemplo, se estiver trabalhando no servidor, execute apenas `npx nx worker twenty-server`
+
+**Se não funcionar:**
+Se você tentou executar apenas `npx nx run twenty-server:start` no WSL e está falhando com o erro de memória abaixo:
+
+`ERRO FATAL: Marcação ineficaz perto do limite de heap Alocação falhou - heap do JavaScript sem memória`
+
+Uma solução alternativa é executar o seguinte comando no seu terminal, ou adicioná-lo ao seu perfil `.bashrc` para que ele seja aplicado automaticamente:
+
+`export NODE_OPTIONS="--max-old-space-size=8192"`
+
+O parâmetro --max-old-space-size=8192 define um limite superior de 8GB para o heap do Node.js; o uso escala conforme as demandas da aplicação.
+Referência: https://stackoverflow.com/questions/56982005/where-do-i-set-node-options-max-old-space-size-2048
+
+**Se não funcionar:**
+Investigue quais processos estão consumindo a maior parte da RAM do seu computador. Em Vinte anos, notamos que algumas extensões de código VS estavam ocupando uma grande quantidade de RAM, por isso as desativamos temporariamente.
+
+**Se não funcionar:**
+Reiniciar sua máquina ajuda a limpar os processos fantasmas.
+
+#### Ao executar `npx nx start`, há logs estranhos [0] e [1]
+
+Isso é esperado, pois o comando `npx nx start` está executando mais comandos por trás dos bastidores
+
+#### Nenhum email é enviado
+
+Na maioria das vezes, isso ocorre porque o `worker` não está sendo executado em segundo plano. Tente executar
+
+```
+npx nx worker twenty-server
+```
+
+#### Não é possível conectar minha conta do Microsoft 365 a Vinte
+
+Na maioria das vezes, é porque seu administrador não ativou a Licença Microsoft 365 para sua conta. Verifique [https://admin.microsoft.com/](https://admin.microsoft.com/Adminportal/Home).
+
+Se você tem um código de erro `AADSTS50020`, provavelmente significa que você está usando uma conta pessoal da Microsoft. Isso ainda não é suportado. Mais informações [aqui](https://learn.microsoft.com/fr-fr/troubleshoot/entra/entra-id/app-integration/error-code-aadsts50020-user-account-identity-provider-does-not-exist)
+
+#### Ao executar o `yarn`, avisos aparecem no console
+
+Os avisos informam sobre a obtenção de dependências adicionais que não estão explicitamente declaradas em `package.json`, portanto, desde que não apareça nenhum erro crítico, tudo deve funcionar como esperado.
+
+#### Quando um usuário acessa a página de login, um erro sobre um usuário não autorizado a tentar acessar um espaço de trabalho aparece nos logs
+
+Isso é esperado, já que o usuário não está autorizado ao se desconectar, pois sua identidade não foi verificada.
+
+#### Como verificar se seu worker está em execução?
+
+* Vá para [webhook-test.com](https://webhook-test.com/) e copie **Sua URL de Webhook exclusiva**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test.jpg" alt="Teste de webhook" />
+</div>
+
+* Abra seu aplicativo Twenty, navegue até `/settings`, e ative a alternância **Avançado** na parte inferior esquerda da tela.
+* Crie um novo webhook.
+* Cole **Sua URL Webhook Única** no campo **Endpoint Url** no Twenty. Defina os **Filtros** para `Companies` e `Created`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-settings.jpg" alt="Configurações de webhook" />
+</div>
+
+* Vá para `/objects/companies` e crie um novo registro de empresa.
+* Retorne para [webhook-test.com](https://webhook-test.com/) e verifique se uma nova **solicitação POST** foi recebida.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/self-hosting/webhook-test-result.jpg" alt="Resultado do teste de webhook" />
+</div>
+
+* Se uma **solicitação POST** for recebida, seu worker está funcionando com sucesso. Caso contrário, você precisa solucionar problemas no seu worker.
+
+#### Front-end falha ao iniciar e retorna erro TS5042: Opção 'projeto' não pode ser misturado com arquivos de origem na linha de comando
+
+Comente o plugin checker em `packages/twenty-ui/vite-config.ts`, como mostrado no exemplo abaixo:
+
+```
+plugins: [
+      react({ jsxImportSource: 'react' }),
+      tsconfigPaths(),
+      svgr(),
+      dts(dtsConfig),
+      // checker(checkersConfig),
+      wyw({
+        include: [
+          '**/OverflowingTextWithTooltip.tsx',
+          '**/Chip.tsx',
+          '**/Tag.tsx',
+          '**/Avatar.tsx',
+          '**/AvatarChip.tsx',
+        ],
+        babelOptions: {
+          presets: ['@babel/preset-typescript', '@babel/preset-react'],
+        },
+      }),
+    ],
+```
+
+#### Painel administrativo não acessível
+
+Execute `UPDATE core."user" SET "canAccessFullAdminPanel" = TRUE WHERE email = 'you@yourdomain.com';` no contêiner do banco de dados para obter acesso ao painel de administração.
+
+#### Ao executar um fluxo de trabalho, a execução do fluxo de trabalho falha com "A execução da função de lógica está desativada. Defina LOGIC_FUNCTION_TYPE como LOCAL ou LAMBDA para ativar."
+
+Em produção, as funções de lógica estão desativadas por padrão. Defina a variável de ambiente `LOGIC_FUNCTION_TYPE` como `LOCAL` ou `LAMBDA` para ativá-las. Isso pode ser configurado por meio de variáveis de ambiente ou pelas variáveis de banco de dados do painel de administração. Veja o [guia de configuração de Funções de Lógica](/l/pt/developers/self-host/capabilities/setup#logic-functions-available-drivers) para obter detalhes.
+
+#### Quando digito uma mensagem no chat AI, ela não responde imediatamente e preciso atualizar a página para ver a resposta
+
+Isso significa que o seu proxy reverso está faltando a configuração para respostas da API baseadas em fluxo. Abaixo está um exemplo da configuração Nginx:
+
+```
+location ~* ^/api/.*stream|\/graphql\/stream {
+proxy_pass http://twenty_backend;
+proxy_http_version 1.1;
+proxy_set_header Connection "";
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_buffering off;
+proxy_request_buffering off;
+proxy_cache off;
+gzip off;
+#chunked_transfer_encoding off;
+add_header X-Accel-Buffering no always;
+}
+```
+
+### 1 clique Docker Compose
+
+#### Impossível efetuar login
+
+Se você não consegue efetuar login após a configuração:
+
+1. Execute os seguintes comandos:
+   ```bash
+   docker exec -it twenty-server-1 yarn
+   docker exec -it twenty-server-1 npx nx database:reset  --configuration=no-seed
+   ```
+2. Reinicie os contêineres Docker:
+   ```bash
+   docker compose down
+   docker compose up -d
+   ```
+
+Note que o comando `database:reset` irá apagar completamente seu banco de dados e recriá-lo do zero.
+
+#### Problemas de conexão por trás de um proxy reverso
+
+Se você está executando o Twenty por trás de um proxy reverso e está enfrentando problemas de conexão:
+
+1. **Verifique o SERVER_URL:**
+
+   Certifique-se de que o `SERVER_URL` no seu arquivo `.env` corresponda à sua URL de acesso externo, incluindo `https` se o SSL estiver habilitado.
+
+2. **Verifique as configurações do Proxy Reverso:**
+
+   * Confirme que seu proxy reverso está encaminhando corretamente as solicitações para o servidor Twenty.
+   * Certifique-se de que cabeçalhos como `X-Forwarded-For` e `X-Forwarded-Proto` estão configurados corretamente.
+
+3. **Reinicie os Serviços:**
+
+   Após fazer as alterações, reinicie tanto o proxy reverso quanto os contêineres do Twenty.
+
+#### Erro ao carregar uma imagem - permissão negada
+
+Alterar a propriedade do diretório de dados no host de root para outro usuário e grupo resolve esse problema.
+
+#### Erro "File Not Found" ao testar a função Logic no fluxo de trabalho
+
+Execute o comando `yarn command:prod application:rebuild-default-deps` no seu contêiner twenty-server para corrigir o problema de dependências ausentes.
+
+## Obtendo Ajuda
+
+Se encontrar problemas não abordados neste guia:
+
+* Verifique os Logs:
+
+  Veja os logs dos contêineres para mensagens de erro:
+
+  ```bash
+  docker compose logs
+  ```
+
+* Suporte Comunitário:
+
+  Entre em contato com a [comunidade Twenty](https://github.com/twentyhq/twenty/issues) ou [canais de suporte](https://discord.gg/cx5n4Jzs57) para obter assistência.

packages/twenty-docs/l/pt/developers/self-host/capabilities/upgrade-guide.mdx

@@ -0,0 +1,106 @@
+---
+title: Guia de atualização
+icon: arrow-up-right-dots
+---
+
+## Diretrizes gerais
+
+**Sempre faça backup do seu banco de dados antes de iniciar o processo de atualização** executando:
+
+```bash
+docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
+```
+
+Para restaurar a partir de um backup:
+
+```bash
+cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
+```
+
+Se você usa o Docker Compose, siga estas etapas:
+
+1. Pare o Twenty: `docker compose down`
+2. Altere o valor de `TAG` no arquivo `.env` que está no mesmo diretório do seu `docker-compose.yml`
+3. Inicie o Twenty: `docker compose up -d`
+
+O servidor executa automaticamente todas as migrações de atualização necessárias na inicialização. Nenhum comando manual é necessário.
+
+## Atualização para v2.34+ — PostgreSQL 15 no mínimo
+
+O Twenty v2.34 requer PostgreSQL 15 ou mais recente. A configuração oficial do Docker Compose usa PostgreSQL 16. Se a sua instância se conectar a um banco de dados gerenciado externamente, atualize-o antes de iniciar o servidor v2.34.
+
+## Atualizações entre versões (v1.23+)
+
+A partir da **v1.23**, o Twenty oferece suporte a atualizações entre versões. Você pode pular diretamente de qualquer versão compatível para a versão mais recente sem passar por cada versão intermediária.
+
+Por exemplo, a atualização da v1.23 diretamente para a v2.0 é totalmente suportada.
+
+## Atualizando para a v2.5+ — envelope de criptografia em repouso
+
+A partir da **v2.5**, Twenty armazena segredos em repouso (tokens OAuth, variáveis de aplicação, chaves privadas de chaves de assinatura, valores de configuração sigilosos, segredos TOTP) dentro de um envelope versionado `enc:v2:` criptografado com `ENCRYPTION_KEY` (ou `APP_SECRET` se `ENCRYPTION_KEY` não estiver definido).
+
+A primeira inicialização na v2.5 executa comandos de atualização lentos que **preenchem retroativamente** as linhas existentes no novo envelope. Eles são idempotentes — interromper e reiniciar o servidor retoma do ponto em que parou —, mas podem demorar em bancos de dados grandes. Você pode monitorar o progresso com `upgrade:status`.
+
+Você deve definir uma `ENCRYPTION_KEY` dedicada **antes** da atualização para a v2.5, para que o preenchimento retroativo grave as linhas sob ela desde o início. Trocar as chaves após o preenchimento retroativo exige uma [rotação](/l/pt/developers/self-host/capabilities/key-rotation).
+
+## Rotação de segredos e chaves de assinatura
+
+Para tarefas operacionais do dia a dia, como rotacionar a `ENCRYPTION_KEY`, rotacionar a chave de assinatura JWT ou revogar uma chave de assinatura vazada, consulte o [guia de rotação de chaves](/l/pt/developers/self-host/capabilities/key-rotation) dedicado.
+
+## Verificando o status da atualização
+
+O comando `upgrade:status` permite inspecionar o estado atual da sua instância e das migrações dos espaços de trabalho. É útil para depurar problemas de atualização ou ao abrir uma solicitação de suporte.
+
+Execute-o a partir do contêiner do servidor:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
+```
+
+Exemplo de saída:
+
+```sh
+APP_VERSION: v1.23.0
+
+Instance
+    Inferred version: 1.23.0
+    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
+    Status:           Up to date
+    Executed by:      v1.23.0
+    At:               2026-04-16T11:43:58.823Z
+
+Workspace
+  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
+      Inferred version: 1.23.0
+      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
+      Status:           Up to date
+      Executed by:      v1.23.0
+      At:               2026-04-16T11:44:09.361Z
+
+Summary
+    Instance: Up to date
+    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
+```
+
+### Opções
+
+| Opção                     | Descrição                                                                                            |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `-w, --workspace-id <id>` | Restringe a um espaço de trabalho específico. Pode ser passada várias vezes.                         |
+| `-f, --failed-only`       | Oculta os espaços de trabalho atualizados; mostra apenas os que estão desatualizados e os com falha. |
+
+## Resolução de Problemas
+
+Se a atualização falhar em alguns espaços de trabalho, o servidor não avançará além da etapa com falha. Reiniciar o servidor (`docker compose up -d`) tentará novamente a atualização a partir de onde parou.
+
+Para identificar rapidamente os problemas, execute:
+
+```bash
+docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
+```
+
+Isso mostra apenas os espaços de trabalho que estão desatualizados ou com falha, juntamente com a mensagem de erro de cada falha.
+
+## Antes da v1.23
+
+Se a sua instância for anterior à v1.23, você deve atualizar incrementalmente por cada versão principal marcada (da v1.6 para a v1.7, depois da v1.7 para a v1.8 e assim por diante) até chegar à v1.23. A partir daí, você pode pular diretamente para a versão mais recente.

packages/twenty-docs/l/pt/developers/self-host/self-host.mdx

@@ -0,0 +1,26 @@
+---
+title: Auto-hospedagem
+description: Implante e gerencie o Twenty na sua própria infraestrutura.
+---
+
+<Frame>
+  <img src="/images/user-guide/what-is-twenty/20.png" alt="IA" />
+</Frame>
+
+## Visão geral
+
+O Twenty pode ser auto-hospedado na sua própria infraestrutura, oferecendo controle total sobre seus dados e a implantação.
+
+## Por que auto-hospedar?
+
+* **Propriedade dos dados**: Mantenha todos os dados de CRM nos seus próprios servidores
+* **Conformidade**: Atenda aos requisitos regulatórios de residência de dados
+* **Personalização**: Acesso total para modificar e estender a plataforma
+
+## Primeiros passos
+
+<CardGroup cols={2}>
+  <Card title="Docker Compose" icon="docker" href="/l/pt/developers/self-host/capabilities/docker-compose">
+    Configuração rápida com Docker
+  </Card>
+</CardGroup>