> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Subpath

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

> [!NOTE]
>
> Custom subpath deployments are currently under internal review. If you need early access, please reach out via
> [GitHub Discussions](https://github.com/formbricks/formbricks/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 the two variables expect a different path: `WEBAPP_URL` uses the
  app root, while `BETTER_AUTH_URL` uses 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](https://formbricks.com/docs/self-hosting/configuration/file-uploads.md).

### Configure environment variables

Add the following variables to the environment you use for builds (local, CI, or Docker build args):

```bash theme={null}
BASE_PATH="/custom-path"
WEBAPP_URL="https://yourdomain.com/custom-path"
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:

```bash theme={null}
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`/`BETTER_AUTH_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` and `BETTER_AUTH_URL` 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.