# Como instalar RustFS e integrar ao Typebot no Easypanel

Tutorial de instalação limpa do RustFS 1.0.4, armazenamento S3, domínio gratuito do Easypanel e integração com Typebot.

Fonte: https://lab.leonardoamoyr.com/prompts/typebot-rustfs

## Ficha do tutorial

| Item | Detalhe |
|---|---|
| Versões testadas | RustFS `1.0.4`; Typebot Builder/Viewer `3.19.1` (valide as tags disponíveis antes de usar) |
| Testado em | 10/11/2026 |
| Revisado em | 10/11/2026 |
| Público | Iniciantes que já possuem Easypanel instalado numa VPS |

## Antes de começar

> [!NOTE]
> Versões futuras do RustFS, do Typebot, do Easypanel ou dos templates podem ter telas, nomes de campos e opções diferentes das descritas aqui. Este guia reflete o ambiente testado em 10/11/2026.

Este guia pressupõe uma **instalação nova**, sem dados a preservar. Você precisará de uma VPS com Easypanel funcionando, do template RustFS e de uma instalação Typebot Builder/Viewer. Não remova volumes de instalações existentes que já contenham dados.

> [!WARNING]
> **Segurança:** todos os nomes de usuário, chaves e senhas abaixo são exemplos. Crie valores únicos e fortes. O armazenamento deve ter backup externo; um volume persistente não é um backup.

## 1. Instalar o template RustFS

No Easypanel, abra o projeto desejado e clique em **Service → Templates → RustFS**. Antes do primeiro Deploy, altere a imagem Docker para:

```text
rustfs/rustfs:1.0.4
```

O template usado nos testes tinha uma imagem alpha antiga, que foi substituída.

## 2. Configurar o Environment do RustFS

Em **RustFS → Environment**, utilize:

```env
RUSTFS_VOLUMES=/data
RUSTFS_ADDRESS=0.0.0.0:9000
RUSTFS_CONSOLE_ADDRESS=0.0.0.0:9001
RUSTFS_CONSOLE_ENABLE=true
RUSTFS_CORS_ALLOWED_ORIGINS=*
RUSTFS_CONSOLE_CORS_ALLOWED_ORIGINS=*
RUSTFS_ACCESS_KEY=ESCOLHA_UM_USUARIO_ADMIN_UNICO
RUSTFS_SECRET_KEY=CRIE_UMA_SENHA_FORTE_UNICA
RUSTFS_OBS_LOGGER_LEVEL=info
RUSTFS_OBJECT_CACHE_ENABLE=true
RUSTFS_OBJECT_CACHE_TTL_SECS=300
```

**Importante:** `RUSTFS_VOLUMES=/data` configura um único caminho de dados. Nos testes, a configuração padrão com `/data/rustfs{0...3}` causou um erro fatal porque os quatro diretórios estavam no mesmo disco físico. **Não** use `RUSTFS_UNSAFE_BYPASS_DISK_CHECK=true` para contornar isso em produção.

As origens `*` foram usadas na demonstração. Em produção, restrinja as origens às URLs necessárias.

## 3. Criar um único volume persistente

> [!CAUTION]
> **Somente para instalação limpa.** Este procedimento remove as montagens de dados padrão do template. Não o execute em uma instalação RustFS que já contenha dados: você pode perder arquivos.

Em **RustFS → Mounts**, na instalação limpa, remova as montagens de dados padrão:

| Volume | Caminho antigo |
|---|---|
| `data0` | `/data/rustfs0` |
| `data1` | `/data/rustfs1` |
| `data2` | `/data/rustfs2` |
| `data3` | `/data/rustfs3` |

Crie uma nova montagem com **Add Volume Mount**:

| Campo | Valor |
|---|---|
| Name | `rustfs-data` |
| Mount Path | `/data` |

Mantenha a montagem de logs do template, se existir. Faça **Deploy**. Os logs devem incluir linhas semelhantes a:

```text
Initializing data directories: /data
Initializing log directory: /logs
Starting: /usr/bin/rustfs /data
```

A inicialização sem erro fatal é um indício positivo, mas o teste de saúde da API será a confirmação.

## 4. Publicar console e API em dois domínios HTTPS

O RustFS usa duas portas internas diferentes:

| Serviço | Porta | Finalidade |
|---|---:|---|
| Console | `9001` | Interface administrativa |
| API S3 | `9000` | Upload e acesso a objetos pelo Typebot |

No Easypanel, configure o domínio do console com destino `HTTP:9001` e crie um segundo domínio para a API com destino `HTTP:9000`. Você pode usar os domínios gratuitos `.easypanel.host` oferecidos pela sua instalação, quando disponíveis.

**Exemplo fictício (substitua pelos domínios da sua instalação):**

```text
Console: https://meu-rustfs.exemplo123.easypanel.host
API S3:  https://meu-rustfs-s3.exemplo123.easypanel.host
```

No formulário de domínio da API:

| Campo | Configuração |
|---|---|
| HTTPS | Ligado |
| Host | `SEU-HOST-S3.easypanel.host` **sem** `https://` e **sem** `/` final |
| Path (origem) | `/` |
| Destination Protocol | `HTTP` |
| Destination Port | `9000` |
| Destination Path | `/` |

> [!NOTE]
> **Erro 404 que resolvemos:** um `/` inserido no final do campo **Host** fez o Easypanel gerar a regra ``Host(`dominio.host/`)``, que não correspondia ao hostname real. **Não remova a barra dos campos Path; remova apenas a barra indevida do Host.**

Salve a configuração e faça Deploy se o Easypanel solicitar.

## 5. Testar a API S3

Abra no navegador:

```text
https://SEU-HOST-S3.easypanel.host/health/ready
```

O esperado é **HTTP 200**, com um JSON que inclua:

```json
{
  "ready": true,
  "service": "rustfs-endpoint",
  "status": "ok"
}
```

O JSON real contém outros campos, incluindo estado do armazenamento e versão.

## 6. Criar o bucket `typebot`

Acesse o console RustFS com suas credenciais administrativas. Em **Buckets → Create Bucket**, crie:

```text
typebot
```

Aplique ao bucket uma política **Custom** que permita leitura anônima **apenas** de objetos sob `public/`:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicRead",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::typebot/public/*"
    }
  ]
}
```

Não conceda acesso público de escrita ao bucket.

## 7. Configurar o CORS do bucket

Em **Bucket → Settings → CORS**, confira se o método `POST` está permitido. A configuração ampla abaixo funcionou no ambiente de aula:

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag"]
    }
  ]
}
```

Para produção, prefira origens específicas do Builder e do Viewer e somente os métodos necessários. **O `POST` foi indispensável para o upload testado.**

## 8. Criar credenciais S3 para o Typebot

No console RustFS, crie uma Access Key e Secret Key próprias para a aplicação, com permissões necessárias ao bucket `typebot`. Não reutilize as credenciais administrativas se for possível usar credenciais restritas. Guarde os valores com segurança.

## 9. Configurar S3 no Typebot Builder e Viewer

No Easypanel, abra **Typebot Builder → Environment** e adicione:

```env
S3_ACCESS_KEY=SUA_ACCESS_KEY
S3_SECRET_KEY=SUA_SECRET_KEY
S3_BUCKET=typebot
S3_ENDPOINT=SEU-HOST-S3.easypanel.host
S3_SSL=true
S3_REGION=us-east-1
```

Adicione **as mesmas variáveis S3** em **Typebot Viewer → Environment**. O `S3_ENDPOINT` usa somente o hostname, sem `https://`, sem caminho e sem barra final. Salve e faça Deploy nos dois serviços.

## 10. Login com GitHub (opcional; apenas Builder)

Se não quiser configurar SMTP, use GitHub OAuth. Crie uma OAuth App em:

https://github.com/settings/developers

Preencha:

| Campo | Valor |
|---|---|
| Application name | `Typebot` |
| Homepage URL | `https://SEU-HOST-BUILDER.easypanel.host` |
| Authorization callback URL | `https://SEU-HOST-BUILDER.easypanel.host/api/auth/callback/github` |
| Allow wildcard matching | Desmarcado |
| Enable Device Flow | Desmarcado |

No **Environment do Builder** (não no Viewer), adicione:

```env
GITHUB_CLIENT_ID=SEU_CLIENT_ID
GITHUB_CLIENT_SECRET=SEU_CLIENT_SECRET
NEXTAUTH_URL=https://SEU-HOST-BUILDER.easypanel.host
```

No ambiente de teste, a imagem Typebot `3.15.2` retornava à tela de login após autenticação. A atualização para a linha `3.19.x` resolveu o fluxo testado. As imagens utilizadas foram:

```text
baptistearno/typebot-builder:3.19.1
baptistearno/typebot-viewer:3.19.1
```

**Antes de atualizar uma instalação com dados:** faça backup do PostgreSQL, confirme a compatibilidade e mantenha Builder e Viewer na mesma versão. Não altere `ENCRYPTION_SECRET` de uma instalação existente sem compreender as consequências.

## 11. Validar a integração

1. Entre no Builder (por GitHub, se configurado).
2. Crie um Typebot simples com uma mensagem e um bloco de imagem.
3. Envie uma imagem pelo Builder.
4. No RustFS, abra o bucket `typebot` e confira se o arquivo apareceu sob `public/workspaces/...`.
5. Abra a URL pública da imagem e confirme que carrega sem autenticação.
6. Publique o bot e teste-o no Viewer. Se houver upload de arquivo pelo Viewer, teste também esse fluxo.

**Resultado observado no teste de 10/11/2026:** o upload de imagem pelo Builder foi bem-sucedido, e o objeto apareceu no console RustFS com tipo `image/png`.

## Solução rápida de problemas

| Sintoma | Causa provável / ação |
|---|---|
| `[FATAL] local erasure endpoints must use distinct physical disks` | Template configurado com quatro diretórios no mesmo disco; use `RUSTFS_VOLUMES=/data` e um volume persistente em `/data` numa instalação nova. |
| `404 Not Found` com página do Easypanel na API | Confira se o campo **Host** não termina em `/`, se a porta de destino é `9000` e se a rota foi salva. |
| `/health/ready` retorna `200` mas upload falha | Confira CORS do bucket, especialmente `POST`, política e credenciais. |
| GitHub autoriza e volta para o login | Confira a versão do Typebot, `NEXTAUTH_URL`, callback e logs do Builder. |
| Imagem aparece no bucket mas não abre publicamente | Confira a política `s3:GetObject` limitada a `typebot/public/*` e a URL pública correta. |

## Checklist do aluno

- [ ] Instalei RustFS com a imagem `rustfs/rustfs:1.0.4`.
- [ ] Configurei `RUSTFS_VOLUMES=/data`.
- [ ] Criei volume persistente único em `/data`.
- [ ] Configurei credenciais administrativas fortes.
- [ ] Fiz Deploy sem erro fatal.
- [ ] Publiquei console `9001` e API S3 `9000`.
- [ ] Testei `/health/ready` com HTTP 200.
- [ ] Criei bucket `typebot`.
- [ ] Configurei política pública apenas para `public/*`.
- [ ] Conferi CORS com `POST`.
- [ ] Criei credenciais S3 da aplicação.
- [ ] Configurei S3 no Builder e no Viewer.
- [ ] Configurei GitHub OAuth no Builder (opcional).
- [ ] Testei upload, acesso público e bot publicado.
- [ ] Planejei backup externo dos dados.
