[[development-basepath]]
=== Considerations for basePath

All communication from the Kibana UI to the server needs to respect the
`server.basePath`. Here are the "blessed" strategies for dealing with this
based on the context:

[float]
==== Getting a static asset url

Use webpack to import the asset into the build. This will give you a URL in
JavaScript and gives webpack a chance to perform optimizations and
cache-busting.

["source","shell"]
-----------
// in plugin/public/main.js
import uiChrome from 'ui/chrome';
import logoUrl from 'plugins/facechimp/assets/banner.png';

uiChrome.setBrand({
  logo: `url(${logoUrl}) center no-repeat`
});
-----------

[float]
==== API requests from the front-end

Use `chrome.addBasePath()` to append the basePath to the front of the url.

["source","shell"]
-----------
import chrome from 'ui/chrome';
$http.get(chrome.addBasePath('/api/plugin/things'));
-----------

[float]
==== Server side

Append `request.getBasePath()` to any absolute URL path.

["source","shell"]
-----------
const basePath = server.config().get('server.basePath');
server.route({
  path: '/redirect',
  handler(request, h) {
    return h.redirect(`${request.getBasePath()}/otherLocation`);
  }
});
-----------

[float]
==== BasePathProxy in dev mode

The Kibana dev server automatically runs behind a proxy with a random
`server.basePath`. This way developers will be constantly verifying that their
code works with basePath, while they write it.

To accomplish this the `serve` task does a few things:

1. change the port for the server to the `dev.basePathProxyTarget` setting (default `5603`)
2. start a `BasePathProxy` at `server.port`
  - picks a random 3-letter value for `randomBasePath`
  - redirects from `/` to `/{randomBasePath}`
  - redirects from `/{any}/app/{appName}` to `/{randomBasePath}/app/{appName}` so that refreshes should work
  - proxies all requests starting with `/{randomBasePath}/` to the Kibana server

If you're writing scripts that interact with the Kibana API, the base path proxy will likely
make this difficult. To bypass the base path proxy for a single request, prefix urls with
`__UNSAFE_bypassBasePath` and the request will be routed to the development Kibana server.

["source","shell"]
-----------
curl "http://elastic:changeme@localhost:5601/__UNSAFE_bypassBasePath/api/status"
-----------

This proxy can sometimes have unintended side effects in development, so when
needed you can opt out by passing the `--no-base-path` flag to the `serve` task
or `yarn start`.

["source","shell"]
-----------
yarn start --no-base-path
-----------