feat: new data migrations approach (#4466)

Co-authored-by: Piyush Gupta <56182734+gupta-piyush19@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Piyush Gupta <piyushguptaa2z123@gmail.com>
Co-authored-by: Matthias Nannt <mail@matthiasnannt.com>

apps/docs/app/self-hosting/migration-guide/page.mdx

@@ -8,6 +8,96 @@ export const metadata = {
 
 # Migration Guide
 
+## v3.0
+
+<Note>
+  **Don't upgrade to 3.0 if you need SSO and user identification**
+
+With Formbricks 3.0, we're making some strategic changes to ensure long-term sustainability while keeping our core commitment to open source. While the Community Edition <a href="https://formbricks.com/blog/formbricks-3-0">got more powerful</a>, we're moving <a href="/docs/self-hosting/license">some advanced features</a> to the Enterprise Edition.
+
+If you update to 3.0 and run the data migration, there is no way back to 2.7.2 - if you need to use SSO or one of the other previously free features, either stick with 2.7.x or <a href="mailto:hola@formbricks.com">reach out</a> for a custom quote.
+
+</Note>
+
+<Note>
+  This major release introduces a new improved approach for data migrations. If you are on a version older
+  than v2.7, you need to migrate step-by-step through the earlier versions first (e.g. 2.4 → 2.5 → 2.6 → 2.7).
+  After you have reached v2.7, you can upgrade directly to any v3.x and future release without performing each
+  intermediate migration.
+</Note>
+
+### Steps to Migrate
+
+This guide is for users who are self-hosting Formbricks using our one-click setup. If you are using a different setup, you might adjust the commands accordingly.
+
+To run all these steps, please navigate to the `formbricks` folder where your `docker-compose.yml` file is located.
+
+1. **Backup your Database**: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database:
+
+<Col>
+<CodeGroup title="Backup Postgres">
+
+```bash
+docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.0_$(date +%Y%m%d_%H%M%S).dump
+```
+
+</CodeGroup>
+</Col>
+
+<Note>
+  If you run into “No such container”, use `docker ps` to find your container name, e.g.
+  `formbricks_postgres_1`.
+</Note>
+
+<Note>
+  If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a
+  restore scenario you will need to use `psql` then with an empty `formbricks` database.
+</Note>
+
+2. Pull the latest version of Formbricks:
+
+<Col>
+<CodeGroup title="Stop the containers">
+
+```bash
+docker compose pull
+```
+
+</CodeGroup>
+</Col>
+
+3. Stop the running Formbricks instance & remove the related containers:
+
+<Col>
+<CodeGroup title="Stop the containers">
+
+```bash
+docker compose down
+```
+
+</CodeGroup>
+</Col>
+
+4. Restarting the containers with the latest version of Formbricks:
+
+<Col>
+<CodeGroup title="Restart the containers">
+
+```bash
+docker compose up -d
+```
+
+</CodeGroup>
+</Col>
+
+When you start the latest version of Formbricks, it will automatically detect and run any necessary data migrations during startup. There is no need to run any manual migration steps or pull any separate migration images.
+
+5. Access your updated instance
+
+Once the containers are up and running, simply navigate to the same URL as before to access your fully migrated Formbricks instance.
+
+That’s it! The new workflow ensures that your Formbricks instance will always remain up-to-date with the latest schema changes as soon as you run the updated container.
+
 ## v2.7
 
 <Note>

apps/docs/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "clean": "rimraf .turbo node_modules .next",
-    "dev": "next dev --turbopack --port 3001",
+    "dev": "next dev --port 3001",
     "build": "next build",
     "start": "next start",
     "lint": "next lint",