# How to install RustFS and integrate it with Typebot on Easypanel

A tutorial for a fresh RustFS 1.0.4 installation, S3 storage, a free Easypanel domain, and Typebot integration.

Source: https://lab.leonardoamoyr.com/en/prompts/typebot-rustfs

## Tutorial overview

| Item | Details |
|---|---|
| Tested versions | RustFS `1.0.4`; Typebot Builder/Viewer `3.19.1` (check the available tags before using them) |
| Tested on | November 10, 2026 |
| Reviewed on | November 10, 2026 |
| Audience | Beginners who already have Easypanel installed on a VPS |

## Before you begin

> [!NOTE]
> Future versions of RustFS, Typebot, Easypanel, or the templates may have different screens, field names, and options from those described here. This guide reflects the environment tested on November 10, 2026.

This guide assumes a **fresh installation**, with no data to preserve. You will need a VPS running Easypanel, the RustFS template, and a Typebot Builder/Viewer installation. Do not remove volumes from existing installations that already contain data.

> [!WARNING]
> **Security:** all usernames, keys, and passwords below are examples. Create strong, unique values. Your storage needs an external backup; a persistent volume is not a backup.

## 1. Install the RustFS template

In Easypanel, open the project you want to use and click **Service → Templates → RustFS**. Before the first deployment, change the Docker image to:

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

The template used in testing had an old alpha image, which was replaced.

## 2. Configure the RustFS environment

Under **RustFS → Environment**, use:

```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
```

**Important:** `RUSTFS_VOLUMES=/data` configures a single data path. In testing, the default `/data/rustfs{0...3}` configuration caused a fatal error because all four directories were on the same physical disk. **Do not** use `RUSTFS_UNSAFE_BYPASS_DISK_CHECK=true` to work around this in production.

The `*` origins were used for the demonstration. In production, restrict origins to the required URLs.

## 3. Create a single persistent volume

> [!CAUTION]
> **For fresh installations only.** This procedure removes the template's default data mounts. Do not run it on a RustFS installation that already contains data: you could lose files.

Under **RustFS → Mounts**, remove the default data mounts in your fresh installation:

| Volume | Old path |
|---|---|
| `data0` | `/data/rustfs0` |
| `data1` | `/data/rustfs1` |
| `data2` | `/data/rustfs2` |
| `data3` | `/data/rustfs3` |

Create a new mount with **Add Volume Mount**:

| Field | Value |
|---|---|
| Name | `rustfs-data` |
| Mount Path | `/data` |

Keep the template's log mount, if there is one. Click **Deploy**. The logs should include lines similar to these:

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

Starting without a fatal error is a positive sign, but the API health check will confirm that it is working.

## 4. Publish the console and API on two HTTPS domains

RustFS uses two different internal ports:

| Service | Port | Purpose |
|---|---:|---|
| Console | `9001` | Administration interface |
| S3 API | `9000` | Uploads and object access through Typebot |

In Easypanel, configure the console domain to point to `HTTP:9001` and create a second domain for the API pointing to `HTTP:9000`. You can use the free `.easypanel.host` domains offered by your installation, when available.

**Fictitious example (replace with your installation's domains):**

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

In the API domain form:

| Field | Setting |
|---|---|
| HTTPS | Enabled |
| Host | `SEU-HOST-S3.easypanel.host` **without** `https://` and **without** a trailing `/` |
| Path (source) | `/` |
| Destination Protocol | `HTTP` |
| Destination Port | `9000` |
| Destination Path | `/` |

> [!NOTE]
> **The 404 error we resolved:** a `/` at the end of the **Host** field caused Easypanel to generate the rule ``Host(`dominio.host/`)``, which did not match the actual hostname. **Do not remove the slash from the Path fields; remove only the unwanted slash from Host.**

Save the configuration and deploy if Easypanel asks you to.

## 5. Test the S3 API

Open this in your browser:

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

The expected response is **HTTP 200**, with JSON that includes:

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

The actual JSON contains other fields, including storage status and version.

## 6. Create the `typebot` bucket

Sign in to the RustFS console with your administrator credentials. Under **Buckets → Create Bucket**, create:

```text
typebot
```

Apply a **Custom** policy to the bucket that allows anonymous reads **only** for objects under `public/`:

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

Do not grant public write access to the bucket.

## 7. Configure bucket CORS

Under **Bucket → Settings → CORS**, check that the `POST` method is allowed. The broad configuration below worked in the classroom environment:

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

For production, use specific Builder and Viewer origins and only the methods you need. **`POST` was essential for the upload we tested.**

## 8. Create S3 credentials for Typebot

In the RustFS console, create a dedicated Access Key and Secret Key for the application, with the required permissions for the `typebot` bucket. Use restricted credentials instead of reusing administrator credentials whenever possible. Store the values securely.

## 9. Configure S3 in Typebot Builder and Viewer

In Easypanel, open **Typebot Builder → Environment** and add:

```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
```

Add **the same S3 variables** under **Typebot Viewer → Environment**. `S3_ENDPOINT` takes only the hostname, without `https://`, a path, or a trailing slash. Save and deploy both services.

## 10. Sign in with GitHub (optional; Builder only)

If you do not want to configure SMTP, use GitHub OAuth. Create an OAuth App at:

https://github.com/settings/developers

Fill in:

| Field | Value |
|---|---|
| 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 | Unchecked |
| Enable Device Flow | Unchecked |

In the **Builder environment** (not Viewer), add:

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

In the test environment, the Typebot `3.15.2` image returned to the login screen after authentication. Updating to the `3.19.x` series resolved the login flow we tested. These were the images used:

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

**Before updating an installation that contains data:** back up PostgreSQL, confirm compatibility, and keep Builder and Viewer on the same version. Do not change `ENCRYPTION_SECRET` in an existing installation without understanding the consequences.

## 11. Validate the integration

1. Sign in to Builder (through GitHub, if configured).
2. Create a simple Typebot with a message and an image block.
3. Upload an image through Builder.
4. In RustFS, open the `typebot` bucket and check that the file appeared under `public/workspaces/...`.
5. Open the image's public URL and confirm that it loads without authentication.
6. Publish the bot and test it in Viewer. If Viewer includes a file upload, test that flow too.

**Result observed in the November 10, 2026 test:** the image upload through Builder succeeded, and the object appeared in the RustFS console with type `image/png`.

## Quick troubleshooting

| Symptom | Likely cause / action |
|---|---|
| `[FATAL] local erasure endpoints must use distinct physical disks` | The template has four directories on the same disk; use `RUSTFS_VOLUMES=/data` and a persistent volume at `/data` in a fresh installation. |
| `404 Not Found` with an Easypanel page on the API | Check that the **Host** field has no trailing `/`, the destination port is `9000`, and the route has been saved. |
| `/health/ready` returns `200` but uploads fail | Check bucket CORS, especially `POST`, as well as the policy and credentials. |
| GitHub authorizes access but returns to login | Check the Typebot version, `NEXTAUTH_URL`, callback, and Builder logs. |
| Image appears in the bucket but does not open publicly | Check the `s3:GetObject` policy limited to `typebot/public/*` and the correct public URL. |

## Student checklist

- [ ] I installed RustFS with the `rustfs/rustfs:1.0.4` image.
- [ ] I configured `RUSTFS_VOLUMES=/data`.
- [ ] I created a single persistent volume at `/data`.
- [ ] I configured strong administrator credentials.
- [ ] I deployed without a fatal error.
- [ ] I published the console on `9001` and the S3 API on `9000`.
- [ ] I tested `/health/ready` and received HTTP 200.
- [ ] I created the `typebot` bucket.
- [ ] I configured a public policy for `public/*` only.
- [ ] I checked CORS for `POST`.
- [ ] I created S3 credentials for the application.
- [ ] I configured S3 in Builder and Viewer.
- [ ] I configured GitHub OAuth in Builder (optional).
- [ ] I tested uploads, public access, and the published bot.
- [ ] I planned an external backup of the data.
