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 Formbricks URLs (WEBAPP_URL, NEXTAUTH_URL, webhook targets, OAuth callbacks, MCP clients, 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):
If you use email links, webhooks, or third-party OAuth providers, ensure every URL you register includes the prefix. MCP clients must use https://yourdomain.com/custom-path/api/mcp, and OAuth discovery is served from https://yourdomain.com/custom-path/.well-known/oauth-authorization-server/api/auth.

​
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:
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 WEBAPP_URL, NEXTAUTH_URL, and BETTER_AUTH_URL (if set) include the prefix. Formbricks derives Better Auth OAuth endpoints under /api/auth.
  • 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.