> ## 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).
</Note>

### 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](/docs/self-hosting/configuration/file-uploads).

### 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"
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

<Steps>
  <Step title="Clone Formbricks and prepare secrets">
    Make sure you have the repository checked out and create temporary files (or use <code>--secret</code>) for the
    required build-time secrets such as <code>DATABASE\_URL</code>, <code>ENCRYPTION\_KEY</code>, <code>REDIS\_URL</code>,
    and optional telemetry tokens.
  </Step>

  <Step title="Pass BASE_PATH as a build argument">
    Use the Formbricks web Dockerfile and supply the custom subpath via <code>--build-arg</code>. 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 <code>BASE PATH /custom-path</code>, confirming that Next.js picked up the
    prefix.
  </Step>

  <Step title="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 <code>/custom-path</code> requests forward to
    <code>[http://formbricks-web:3000/custom-path](http://formbricks-web:3000/custom-path)</code> without stripping the prefix.
  </Step>
</Steps>

### 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.