Skip to main content
Custom subpath deployments are currently under internal review. If you need early access, please reach out via GitHub Discussions.

​
When to use a custom subpath

Use a custom subpath (also called a Next.js base path) when your reverse proxy reserves the root domain for another service, but you still want Formbricks to live under the same hostname—for example https://example.com/feedback. Support for a build-time BASE_PATH variable is available in the Formbricks web app so that all internal routes, assets, and sign-in redirects honor the prefix.

​
Requirements and limitations

  • BASE_PATH must be present during pnpm build; changing it afterward requires a rebuild.
  • Official Formbricks Docker images do not accept this flag for technical reasons, so you must build your own image.
  • All public URLs (WEBAPP_URL, NEXTAUTH_URL, webhook targets, OAuth callbacks, etc.) need the same prefix.
  • Your proxy must rewrite /custom-path/* to the Formbricks container while keeping the prefix visible to clients.

​
Configure environment variables

Add the following variables to the environment you use for builds (local, CI, or Docker build args): 
BASE_PATH="/custom-path"
WEBAPP_URL="https://yourdomain.com/custom-path"
NEXTAUTH_URL="https://yourdomain.com/custom-path/api/auth"
If you use email links, webhooks, or third-party OAuth providers, ensure every URL you register includes the prefix.

​
Build a Docker image with a custom subpath

1

Clone Formbricks and prepare secrets

Make sure you have the repository checked out and create temporary files (or use —secret) for the required build-time secrets such as DATABASE_URL, ENCRYPTION_KEY, REDIS_URL, and optional telemetry tokens.
2

Pass BASE_PATH as a build argument

Use the Formbricks web Dockerfile and supply the custom subpath via —build-arg. Example:
docker build \
  --progress=plain \
  --no-cache \
  --build-arg BASE_PATH=/custom-path \
  --secret id=database_url,src=<(printf "postgresql://user:password@localhost:5432/formbricks?schema=public") \
  --secret id=encryption_key,src=<(printf "your-32-character-encryption-key-here") \
  --secret id=redis_url,src=<(printf "redis://localhost:6379") \
  --secret id=sentry_auth_token,src=<(printf "") \
  -f apps/web/Dockerfile \
  -t formbricks-web \
  .
During the build logs you should see BASE PATH /custom-path, confirming that Next.js picked up the prefix.
3

Run the container behind your proxy

Start the resulting image with the same runtime environment variables you normally use (database credentials, mailing provider, etc.). Point your reverse proxy so that /custom-path requests forward to http://formbricks-web:3000/custom-path without stripping the prefix.

​
Verify the deployment

  1. Open https://yourdomain.com/custom-path and complete the onboarding flow.
  2. Create a survey and preview it—embedded scripts now load assets relative to the subpath.
  3. Sign out and confirm the login page still includes /custom-path.

​
Troubleshooting checklist

  • Confirm your build pipeline actually passes BASE_PATH (and, if needed, WEBAPP_URL/NEXTAUTH_URL) into the build stage—check CI logs for the BASE PATH /your-prefix line and make sure custom Dockerfiles or wrappers forward --build-arg BASE_PATH=... correctly.
  • If you cannot log in, double-check that NEXTAUTH_URL includes the prefix and uses the full route to the API as stated above. NextAuth rejects callbacks that do not match exactly.
  • Re-run the Docker build when changing BASE_PATH; simply editing the container environment is not sufficient.
  • Inspect your proxy configuration to ensure it does not rewrite paths internally (e.g., strip_prefix needs to stay disabled).
  • When in doubt, rebuild locally with --progress=plain and verify that the BASE PATH line reflects your prefix.