Custom Subpath

Serve Formbricks from a custom URL prefix when you cannot expose it on the root domain.

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 Next.js-managed routes, assets, and navigation honor the prefix.

Requirements and limitations

• BASE_PATH must be present during pnpm build; changing it afterward requires a rebuild.
• Next.js inlines the base path into the client bundles, so setting BASE_PATH on an already-built official Formbricks image has no effect. You must build your own Formbricks web image with the required value.
• Formbricks-owned public URLs need the prefix, but each variable expects a different path: WEBAPP_URL uses the app root, while NEXTAUTH_URL and optional BETTER_AUTH_URL use the full auth endpoint under /custom-path/api/auth. External webhook target URLs do not need the prefix unless they point to a Formbricks endpoint.
• Known limitation: the browser auth client currently sends login and sign-up requests to /api/auth at the domain root instead of /custom-path/api/auth. Authentication therefore does not work for a true subpath-only deployment, and changing the URL environment variables does not correct the browser request path.
• Your proxy must rewrite /custom-path/* to the Formbricks container while keeping the prefix visible to clients.

Configure object storage separately

BASE_PATH applies only to the Formbricks web application. It does not add the same prefix to RustFS, MinIO, or another S3-compatible storage service, and the custom image described below is a Formbricks image—not a custom storage image.

Keep the S3 API at the root of a dedicated endpoint such as https://files.example.com and set S3_ENDPOINT_URL to that endpoint. Do not route it through an arbitrary prefix such as https://example.com/custom-path/storage: the request path is part of the AWS Signature Version 4 signature, so proxy path rewriting can invalidate signed and presigned requests. Provider settings that expose a management console under a subpath do not change the S3 API base path.

For the complete storage and CORS setup, see File Uploads Configuration.

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"
BETTER_AUTH_URL="https://yourdomain.com/custom-path/api/auth"

If you use third-party OAuth providers, ensure every Formbricks callback 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:

   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/auth/login and confirm the page loads under the prefix.
2. In your browser’s network panel, confirm Next.js assets and navigation requests include /custom-path.
3. Do not use login or onboarding as a successful deployment check until the browser auth-client limitation above is fixed.

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.
• Keep WEBAPP_URL, NEXTAUTH_URL, and BETTER_AUTH_URL (if set) configured as shown above for server-side callbacks and discovery, but note that they do not fix the browser auth-client request path.
• 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.