mirror/formbricks
1
0
Fork 0
mirror of https://github.com/formbricks/formbricks.git synced 2026-04-19 11:11:05 -05:00
Code Issues Packages Projects Releases 162 Wiki Activity

docs: add formbricks 4 migration guide

Browse Source
This commit is contained in:
Matti Nannt
2025-09-19 15:31:10 +02:00
parent 51babf2f98
commit 5a723cd81a
4 changed files with 305 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/docs.json
View File

@@ -260,8 +260,14 @@
{
"group": "Advanced",
"pages": [
"self-hosting/advanced/migration",
"self-hosting/setup/minio-migration",
{
"group": "Migration",
"icon": "arrow-right",
"pages": [
"self-hosting/advanced/migration",
"self-hosting/advanced/migration/minio-migration"
]
},
"self-hosting/advanced/license",
"self-hosting/advanced/license-activation",
{

119
docs/self-hosting/advanced/migration.mdx
View File

@@ -1,13 +1,124 @@
---
title: "Migration"
title: "Migration Guides"
description: "Formbricks Self-hosted version migration"
icon: "arrow-right"
---
### v4.0
## v4.0
- Migrate local uploads to the new MinIO storage (required in 4.0):
see [minio migration](/self-hosting/setup/minio-migration)
Formbricks 4.0 is a **major milestone** that sets up the technical foundation for future iterations and feature improvements. This release focuses on modernizing core infrastructure components to improve reliability, scalability, and enable advanced features going forward.
### What's New in Formbricks 4.0
**🚀 New Enterprise Features:**
- **Quotas Management**: Advanced quota controls for enterprise users
- **Enhanced File Storage**: Improved file handling with better performance and reliability
**🏗️ Technical Foundation Improvements:**
- **Standardized Caching**: Migration from single-instance in-memory cache to dedicated Redis
- **Modern File Storage**: Complete migration to S3-compatible object storage
- **Database Optimization**: Removal of unused database tables and fields for better performance
- **Future-Ready Architecture**: Standardized infrastructure components for upcoming features
### Why These Changes Are Required
**Deprecated Components:**
- **Local File Storage**: No longer supported to improve reliability and enable advanced file features
- **In-Memory Caching**: Replaced with Redis for better performance and multi-instance support
**Benefits of the New Architecture:**
- **Improved Reliability**: Dedicated components for critical functions
- **Better Scalability**: Support for multi-instance deployments
- **Enhanced Performance**: Optimized caching and file storage
- **Future-Proof**: Standardized foundation for upcoming enterprise features
<Warning>
**Important: Migration Required**
Users currently using **one-click hosting** or other setups without dedicated Redis and S3-compatible storage **must migrate** before upgrading to 4.0:
- **File Storage**: Migrate from local storage to MinIO (S3-compatible)
- **Caching**: Configure Redis for caching (automatically handled in one-click setups)
- **Database**: Automatic cleanup will remove unused tables/fields (backup recommended)
</Warning>
### Migration Steps for v4.0
This guide is for users who are **self-hosting Formbricks** using the **one-click setup**. If you have a different setup, you may need to adjust the commands accordingly.
Before running these steps, **navigate to the `formbricks` directory** where your `docker-compose.yml` file is located.
#### 1. Backup your Database
**Critical Step**: Create a complete database backup before proceeding. Formbricks 4.0 will automatically remove unused database tables and fields during startup.
```bash
docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v4.0_$(date +%Y%m%d_%H%M%S).dump
```
<Info>
If you run into "**No such container**", use `docker ps` to find your container name,
e.g. `formbricks_postgres_1`.
</Info>
#### 2. Migrate to MinIO (Required for Local Storage Users)
If your installation currently uses local file storage, you must migrate to MinIO:
```bash
# Download the migration script
curl -fsSL -o migrate-to-minio.sh \
https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/migrate-to-minio.sh
# Make it executable and run
chmod +x migrate-to-minio.sh
./migrate-to-minio.sh
```
For detailed instructions, troubleshooting, and manual migration steps, see the [MinIO migration guide](/self-hosting/advanced/migration/minio-migration).
#### 3. Upgrade to Formbricks 4.0
Once your MinIO migration is complete (if required):
```bash
# Pull the latest version
docker compose pull
# Stop the current instance
docker compose down
# Start with Formbricks 4.0
docker compose up -d
```
#### 4. Automatic Database Migration
When you start Formbricks 4.0 for the first time, it will **automatically**:
- Detect and apply required database schema updates
- Remove unused database tables and fields
- Optimize the database structure for better performance
No manual intervention is required for the database migration.
#### 5. Verify Your Upgrade
- Access your Formbricks instance at the same URL as before
- Test file uploads to ensure MinIO integration works correctly
- Verify that existing surveys and data are intact
- Check that previously uploaded files are accessible
<Info>
**Redis Caching**: For one-click setups, Redis caching is automatically configured. For custom setups, ensure you have Redis configured as per the [configuration documentation](/self-hosting/configuration/environment-variables).
</Info>
### Post-Migration Benefits
After upgrading to Formbricks 4.0, you'll benefit from:
- **Better Performance**: Improved caching and file storage performance
- **Enhanced Reliability**: Dedicated components for critical functions
- **Future Features**: Access to new enterprise features like Quotas Management
- **Scalability**: Foundation for multi-instance deployments
### v3.3

182
docs/self-hosting/advanced/migration/minio-migration.mdx Normal file
View File

@@ -0,0 +1,182 @@
---
title: "Migrate local uploads to MinIO"
description: "Detailed guide for migrating from local file storage to MinIO for Formbricks 4.0"
icon: "cloud"
---
## Why this migration is required
Formbricks 4.0 uses an S3‑compatible object store for all file uploads. For One‑Click installs that previously stored files locally (named volume `uploads` or a host bind like `./uploads`), you must migrate those files to MinIO.
This guide shows a safe, idempotent migration using the script `docker/migrate-to-minio.sh` included in this repository.
<Note>
This migration script is supported on Ubuntu only (Ubuntu 20.04+), requiring Bash 4+ and GNU sed/grep.
</Note>
## Prerequisites
- **DNS Setup**: A subdomain for object storage (e.g., `files.yourdomain.com`) pointing to your server IP
- **System Requirements**: Ubuntu 20.04+ with Bash 4+ and GNU sed/grep
- **Docker/Compose**: Working Docker and Docker Compose installation
- Your One‑Click installation directory (contains `docker-compose.yml`)
## What the script does
The migration script will:
- Add MinIO services (`minio`, `minio-init`) and S3 environment variables to your `docker-compose.yml`
- Ask to restart your Compose stack (you should say Yes)
- Detect your existing upload sources post‑start and migrate them to MinIO:
- Host bind mounts (e.g., `./uploads`)
- Named volume target in the container (legacy: `/home/nextjs/apps/web/uploads` or custom target)
- Absolute `UPLOADS_DIR` in the container if set
- Clean up `docker-compose.yml` after success: removes `UPLOADS_DIR`, removes all `uploads` volume mappings and the root `uploads:` definition
- Optionally restart again to apply the cleanup
The migration is idempotent: you can re‑run it; existing objects are not duplicated.
## Run the migration
From the directory that contains your `docker-compose.yml`:
```bash
# Download the latest script
curl -fsSL -o migrate-to-minio.sh \
https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/migrate-to-minio.sh
# Make it executable
chmod +x migrate-to-minio.sh
# Launch the guided migration
./migrate-to-minio.sh
```
## Verifying the migration
After the migration completes:
1. **Check the UI**: Previously uploaded images/logos/files should load correctly
2. **List bucket contents** to verify files were migrated:
```bash
docker compose run --rm --entrypoint /bin/sh minio-init -lc \
'mc alias set minio http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" && \
mc ls -r "minio/$MINIO_BUCKET_NAME" | head -200'
```
3. **Confirm cleanup**: Your `docker-compose.yml` should no longer contain `UPLOADS_DIR` or `uploads:` volume mappings (post‑cleanup)
## Notes on sources
The script migrates from multiple sources, in order:
- Host bind (absolute path resolved by `docker compose config`)
- Container mount target for named volume `uploads` (e.g., `/home/nextjs/apps/web/uploads` or your custom `.../files/uploads`)
- Absolute `UPLOADS_DIR` (container path)
The relative path/key structure is preserved: `${environmentId}/${accessType}/fileName.ext`
Re‑runs copy only new/changed files (idempotent).
## Troubleshooting
### MinIO 404 on file URLs
If you use virtual‑hosted style (`bucket.files.domain`), ensure Traefik router rule includes wildcard:
```
traefik.http.routers.minio-s3.rule=Host(`files.domain`) || HostRegexp(`{any:.+}.files.domain`)
```
### InvalidAccessKeyId in UI
This happens if keys were rotated between runs. Re‑run the script; it reuses S3\_\* credentials and reattaches policy.
### Undefined volume `minio-data`
Re‑run the script; it ensures `minio-data` exists in the root `volumes:` block.
### List bucket contents
```bash
docker compose run --rm --entrypoint /bin/sh minio-init -lc \
'mc alias set minio http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"; \
mc ls -r "minio/$MINIO_BUCKET_NAME" | head -200'
```
## Manual migration steps
If the automated script doesn't work for your setup, you can perform the migration manually:
### 1. Add MinIO services to docker-compose.yml
Add the following services to your `docker-compose.yml`:
```yaml
services:
# ... your existing services ...
minio:
image: minio/minio:latest
container_name: formbricks-minio
command: server /data --console-address ":9001"
ports:
- "9000:9000"
- "9001:9001"
environment:
MINIO_ROOT_USER: ${S3_ACCESS_KEY}
MINIO_ROOT_PASSWORD: ${S3_SECRET_KEY}
volumes:
- minio-data:/data
minio-init:
image: minio/mc:latest
container_name: formbricks-minio-init
depends_on:
- minio
entrypoint: >
/bin/sh -c "
/usr/bin/mc alias set minio http://minio:9000 ${S3_ACCESS_KEY} ${S3_SECRET_KEY};
/usr/bin/mc mb minio/${S3_BUCKET_NAME} --ignore-existing;
/usr/bin/mc policy set public minio/${S3_BUCKET_NAME};
exit 0;
"
volumes:
# ... your existing volumes ...
minio-data:
```
### 2. Add environment variables
Add these environment variables to your Formbricks service:
```yaml
environment:
# ... your existing environment variables ...
S3_ACCESS_KEY: your-access-key
S3_SECRET_KEY: your-secret-key
S3_REGION: us-east-1
S3_BUCKET_NAME: formbricks-uploads
S3_ENDPOINT_URL: http://minio:9000
```
### 3. Restart and migrate files
1. Restart your stack: `docker compose up -d`
2. Copy files from your local storage to MinIO
3. Remove old volume mappings from docker-compose.yml
4. Restart again to apply changes
## Rollback
Your original `docker-compose.yml` is backed up as `docker-compose.yml.backup.<timestamp>`.
To revert, restore the backup and restart Compose:
```bash
cp docker-compose.yml.backup.<timestamp> docker-compose.yml
docker compose down && docker compose up -d
```
That's it — you're on the new MinIO storage for Formbricks 4.0. ✅

106
docs/self-hosting/setup/minio-migration.mdx
View File

@@ -1,106 +0,0 @@
---
title: Migrate local uploads to MinIO
description: One‑click migration from local file storage to the new MinIO storage required in 4.0
icon: "cloud"
---
## Why this migration is required
Formbricks 4.0 uses an S3‑compatible object store for all file uploads. For One‑Click installs that previously stored files locally (named volume `uploads` or a host bind like `./uploads`), you must migrate those files to MinIO.
This guide shows a safe, idempotent migration using the script `docker/migrate-to-minio.sh` included in this repository.
<Note>
This migration script is supported on Ubuntu only (Ubuntu 20.04+), requiring Bash 4+ and GNU sed/grep.
</Note>
## Prerequisites
- DNS: a subdomain for object storage, e.g. `files.<your-domain>` pointing to your server IP
- Your One‑Click installation directory (contains `docker-compose.yml`)
- Docker/Compose installed and working
## What the script does
- Adds MinIO services (`minio`, `minio-init`) and S3 env vars to `docker-compose.yml`
- Asks to restart your Compose stack (you should say Yes)
- Detects your existing upload sources post‑start and migrates them to MinIO
- Host bind mounts (e.g., `./uploads`)
- Named volume target in the container (legacy: `/home/nextjs/apps/web/uploads` or custom target)
- Absolute `UPLOADS_DIR` in the container if set
- Cleans up `docker-compose.yml` after success: removes `UPLOADS_DIR`, removes all `uploads` volume mappings and the root `uploads:` definition
- Optionally restarts again to apply the cleanup
The migration is idempotent: you can re‑run it; existing objects are not duplicated.
## Run the migration
From the directory that contains your `docker-compose.yml`:
```bash
# Download the latest script
curl -fsSL -o migrate-to-minio.sh \
https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/migrate-to-minio.sh
# Make it executable
chmod +x migrate-to-minio.sh
# Launch the guided migration
./migrate-to-minio.sh
```
## Verifying the migration
- Check the UI: previously uploaded images/logos/files should load
- List bucket contents with `mc` (reuses minio‑init service env):
```bash
docker compose run --rm --entrypoint /bin/sh minio-init -lc \
'mc alias set minio http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" && \
mc ls -r "minio/$MINIO_BUCKET_NAME" | head -200'
```
- Confirm `docker-compose.yml` no longer contains `UPLOADS_DIR` or `uploads:` volume mappings (post‑cleanup)
## Notes on sources
- The script migrates from multiple sources, in order:
- Host bind (absolute path resolved by `docker compose config`)
- Container mount target for named volume `uploads` (e.g., `/home/nextjs/apps/web/uploads` or your custom `.../files/uploads`)
- Absolute `UPLOADS_DIR` (container path)
- The relative path/key structure is preserved: `${environmentId}/${accessType}/fileName.ext`
- Re‑runs copy only new/changed files (idempotent)
## Troubleshooting
- MinIO 404 on file URLs
- If you use virtual‑hosted style (`bucket.files.domain`), ensure Traefik router rule includes wildcard:
```
traefik.http.routers.minio-s3.rule=Host(`files.domain`) || HostRegexp(`{any:.+}.files.domain`)
```
- InvalidAccessKeyId in UI
- Happens if keys rotated between runs. Re‑run the script; it reuses S3\_\* credentials and reattaches policy.
- Undefined volume `minio-data`
- Re‑run; the script ensures `minio-data` exists in the root `volumes:` block.
- List bucket contents
```bash
docker compose run --rm --entrypoint /bin/sh minio-init -lc \
'mc alias set minio http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"; \
mc ls -r "minio/$MINIO_BUCKET_NAME" | head -200'
```
## Rollback
- Your original `docker-compose.yml` is backed up as `docker-compose.yml.backup.<timestamp>`
- To revert, restore the backup and restart Compose:
```bash
cp docker-compose.yml.backup.<timestamp> docker-compose.yml
docker compose down && docker compose up -d
```
That’s it — you’re on the new MinIO storage for Formbricks 4.0. ✅