Self-Hosting

Migration Guide

v2.0

Formbricks v2.0 comes with huge features such as Multi-Language Surveys and Advanced Styling for Surveys. We have also shipped various optimisations, bug fixes & smaller fixes on the way to make your experience more seamless. This guide will help you migrate your existing Formbricks instance to v2.0 without any hassles or build errors.

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:

Backup Postgres

docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.0_$(date +%Y%m%d_%H%M%S).dump
  1. Pull the latest version of Formbricks:

Stop the containers

docker-compose pull
  1. Stop the running Formbricks instance & remove the related containers:

Stop the containers

docker-compose down
  1. Restarting the containers with the latest version of Formbricks:

Restart the containers

docker-compose up -d
  1. Now let's migrate the data to the latest schema:

Migrate the data

docker pull ghcr.io/formbricks/data-migrations:latest && \
docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v2.0" \
  ghcr.io/formbricks/data-migrations:latest

The above command will migrate your data to the latest schema. This is a crucial step to migrate your existing data to the new structure. Only if the script runs successful, changes are made to the database. The script can safely run multiple times.

  1. That's it! Once the migration is complete, you can now access your Formbricks instance at the same URL as before.

App Surveys with @formbricks/js

From this upgrade, we now dynamically fetch the package from our API endpoint and updated the package entrypoints to support both app and website surveys so that you always have the latest version of the package (v2.0.0+).

Old approach: (v1.6.5)

Old Formbricks/js use

import formbricks from "@formbricks/js";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  userId: "<user-id>", // optional
});

New approach: (v2.0.0)

Website surveys:

New Formbricks/js website sdk

import formbricks from "@formbricks/js/website";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  // userId is not supported here
});

App surveys:

New Formbricks/js app sdk

import formbricks from "@formbricks/js/app";

formbricks.init({
  environmentId: "<environment-id>",
  apiHost: "<api-host>",
  userId: "<user-id>", // required
});

v1.6

Formbricks v1.6 comes with a big new features like Advanced Targeting & Segmentation of your end-users along with on-the-fly triggers for surveys and a ton of stability improvements & features. This also involves a few changes in our environment variables. This guide will help you migrate your existing Formbricks instance to v1.6 without any hassles or build errors.

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:

Backup Postgres

docker exec formbricks-quickstart-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v1.6_$(date +%Y%m%d_%H%M%S).dump
  1. Stop the running Formbricks instance & remove the related containers:

Stop the containers

docker-compose down
  1. Restarting the containers will automatically pull the latest version of Formbricks:

Restart the containers

docker-compose up -d
  1. Now let's migrate the data to the latest schema:

Migrate the data

docker run --rm \
  --network=formbricks_default \
  -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \
  -e UPGRADE_TO_VERSION="v1.6" \
  ghcr.io/formbricks/data-migrations:v1.6.1

The above command will migrate your data to the latest schema. This is a crucial step to migrate your existing data to the new structure. Only if the script runs successful, changes are made to the database. The script can safely run multiple times.

  1. That's it! Once the migration is complete, you can now access your Formbricks instance at the same URL as before.

Restoring the database after a failed upgrade

Restore the database

docker exec -i formbricks-quickstart-postgres-1 pg_restore --clean -U postgres -v -d formbricks < formbricks_pre_v1.6_<timestamp_of_your_dump_file>.dump

App Surveys with @formbricks/js

If you are using the @formbricks/js package, please make sure to update it to version ~1.6.5 to use the latest features and improvements.

Upgrade and pin the client package

npm install @formbricks/js@~1.6.5

Deprecated Environment Variables

Environment VariableComments
GITHUB_AUTH_ENABLEDWas used to enable GitHub OAuth, but from v1.6, you can just set the GITHUB_ID and GITHUB_SECRET environment variables.
GOOGLE_AUTH_ENABLEDWas used to enable Google OAuth, but from v1.6, you can just set the GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables.
AZUREAD_AUTH_ENABLEDWas used to enable AzureAD OAuth, but from v1.6, you can just set the AZUREAD_CLIENT_ID, AZUREAD_CLIENT_SECRET & AZUREAD_TENANT_ID environment variables.

v1.2

Formbricks v1.2 ships a lot of features targeting our Link Surveys. We have also improved our security posture to be as robust as ever. However, it also comes with a few breaking changes specifically with the environment variables. This guide will help you migrate your existing Formbricks instance to v1.2 without any hassles or build errors.

New Environment Variables

Environment VariableRequiredRecommended GenerationComments
ENCRYPTION_KEYtrueopenssl rand -hex 32Needed for 2 Factor Authentication
SHORT_URL_BASEfalse<your-short-base-url>Needed if you want to enable shorter links for Link Surveys

Deprecated / Removed Environment Variables

Environment VariableComments
SURVEY_BASE_URLThe WEBAPP_URL is now used to determine the survey base url in all places

v1.1

Formbricks v1.1 includes a lot of new features and improvements. However, it also comes with a few breaking changes specifically with the environment variables. This guide will help you migrate your existing Formbricks instance to v1.1 without losing any data.

Renamed Environment Variables

This was introduced because we got a lot of requests from our users for the ability to define some common environment variables at runtime itself i.e. without having to rebuild the image for the changes to take effect. This is now possible with v1.1. However, due to Next.JS best practices, we had to deprecate the prefix NEXTPUBLIC in the following environment variables:

till v1.0v1.1
NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLEDEMAIL_VERIFICATION_DISABLED
NEXT_PUBLIC_PASSWORD_RESET_DISABLEDPASSWORD_RESET_DISABLED
NEXT_PUBLIC_SIGNUP_DISABLEDSIGNUP_DISABLED
NEXT_PUBLIC_INVITE_DISABLEDINVITE_DISABLED
NEXT_PUBLIC_PRIVACY_URLPRIVACY_URL
NEXT_PUBLIC_TERMS_URLTERMS_URL
NEXT_PUBLIC_IMPRINT_URLIMPRINT_URL
NEXT_PUBLIC_GITHUB_AUTH_ENABLEDGITHUB_AUTH_ENABLED
NEXT_PUBLIC_GOOGLE_AUTH_ENABLEDGOOGLE_AUTH_ENABLED
NEXT_PUBLIC_WEBAPP_URLWEBAPP_URL
NEXT_PUBLIC_IS_FORMBRICKS_CLOUDIS_FORMBRICKS_CLOUD
NEXT_PUBLIC_SURVEY_BASE_URLSURVEY_BASE_URL

Deprecated Environment Variables

  • NEXT_PUBLIC_VERCEL_URL: Was used as Vercel URL (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable to your Vercel URL.
  • RAILWAY_STATIC_URL: Was used as Railway Static URL (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable.
  • RENDER_EXTERNAL_URL: Was used as an external URL to Render (used instead of WEBAPP_URL), but from v1.1, you can just set the WEBAPP_URL environment variable.
  • HEROKU_APP_NAME: Was used to build the App name on a Heroku hosted webapp, but from v1.1, you can just set the WEBAPP_URL environment variable.
  • NEXT_PUBLIC_WEBAPP_URL: Was used for the same purpose as WEBAPP_URL, but from v1.1, you can just set the WEBAPP_URL environment variable.
  • PRISMA_GENERATE_DATAPROXY: Was used to tell Prisma that it should generate the runtime for Dataproxy usage. But its officially deprecated now.

Helper Shell Script

For a seamless migration, below is a shell script for your self-hosted instance that will automatically update your environment variables to be compliant with the new naming conventions.

Docker & Single Script Setup

Now that these variables can be defined at runtime, you can append them inside your x-environment in the docker-compose.yml itself. For a more detailed guide on these environment variables, please refer to the Important Runtime Variables section.

docker-compose.yml

version: "3.3"
x-environment: &environment
  environment:
    # The url of your Formbricks instance used in the admin panel
    WEBAPP_URL:

    # PostgreSQL DB for Formbricks to connect to
    DATABASE_URL: "postgresql://postgres:postgres@postgres:5432/formbricks?schema=public"

    # NextJS Auth
    # @see: https://next-auth.js.org/configuration/options#nextauth_secret
    # You can use: `openssl rand -hex 32` to generate one
    NEXTAUTH_SECRET:

    # Set this to your public-facing URL, e.g., https://example.com
    # You do not need the NEXTAUTH_URL environment variable in Vercel.
    NEXTAUTH_URL: http://localhost:3000

    # PostgreSQL password
    POSTGRES_PASSWORD: postgres

    # Email Configuration
    MAIL_FROM:
    SMTP_HOST:
    SMTP_PORT:
    SMTP_SECURE_ENABLED:
    SMTP_USER:
    SMTP_PASSWORD:

    # Uncomment the below and set it to 1 to disable Email Verification for new signups
    # EMAIL_VERIFICATION_DISABLED:

    # Uncomment the below and set it to 1 to disable Password Reset
    # PASSWORD_RESET_DISABLED:

    # Uncomment the below and set it to 1 to disable Signups
    # SIGNUP_DISABLED:

    # Uncomment the below and set it to 1 to disable loging in with email
    # EMAIL_AUTH_DISABLED:

    # Uncomment the below and set it to 1 to disable Invites
    # INVITE_DISABLED:

    # Uncomment the below and set a value to have your own Privacy Page URL on the signup & login page
    # PRIVACY_URL:

    # Uncomment the below and set a value to have your own Terms Page URL on the auth and the surveys page
    # TERMS_URL:

    # Uncomment the below and set a value to have your own Imprint Page URL on the auth and the surveys page
    # IMPRINT_URL:

    # Uncomment the below and set to 1 if you want to enable GitHub OAuth
    # GITHUB_AUTH_ENABLED:
    # GITHUB_ID:
    # GITHUB_SECRET:

    # Uncomment the below and set to 1 if you want to enable Google OAuth
    # GOOGLE_AUTH_ENABLED:
    # GOOGLE_CLIENT_ID:
    # GOOGLE_CLIENT_SECRET:

Did we miss something? Are you still facing issues migrating your app? Join our Discord! We'd be happy to help!

Was this page helpful?