Clarifies how to configure and access the dashboard in the api & dashboard documentations

This commit is contained in:
Damien Duportal 2019-10-07 14:38:06 +02:00 committed by Traefiker Bot
parent a2cd69b654
commit 3ebed4ff40
2 changed files with 54 additions and 19 deletions

View file

@ -824,7 +824,7 @@ Each root item has been moved to a related section or removed.
## Dashboard
You need to activate the [API](../operations/dashboard.md#enabling-the-dashboard) to access the dashboard.
You need to activate the API to access the [dashboard](../operations/dashboard.md).
As the dashboard access is now secured by default you can either:
* define a [specific router](../operations/api.md#configuration) with the `api@internal` service and one authentication middleware like the following example

View file

@ -10,17 +10,25 @@ The dashboard is the central place that shows you the current active routes hand
<figcaption>The dashboard in action</figcaption>
</figure>
By default, the dashboard is available on `/dashboard` on port `:8080`.
There is also a redirect of `/` to `/dashboard`, but one should not rely on that property as it is bound to change,
and it might make for confusing routing rules anyway.
The dashboard is available at the same location as the [API](./api.md) but on the path `/dashboard/` by default.
!!! info "Did You Know?"
It is possible to customize the dashboard endpoint.
To learn how, refer to the [API documentation](./api.md)
!!! warning "The trailing slash `/` in `/dashboard/` is mandatory"
## Enabling the Dashboard
There are 2 ways to configure and access the dashboard:
To enable the dashboard, you need to enable [Traefik's API](./api.md).
- [Secure mode (Recommended)](#secure-mode)
- [Insecure mode](#insecure-mode)
!!! note ""
There is also a redirect of the path `/` to the path `/dashboard/`,
but one should not rely on that property as it is bound to change,
and it might make for confusing routing rules anyway.
## Secure Mode
This is the **recommended** method.
Start by enabling the dashboard by using the following option from [Traefik's API](./api.md):
```toml tab="File (TOML)"
[api]
@ -51,12 +59,39 @@ api:
--api.dashboard=true
```
!!! important "API/Dashboard Security"
Then specify a router associated to the service `api@internal` to allow:
To secure your dashboard, the use of a `service` named `api@internal` is mandatory and requires the definition of a router using one or more security [middlewares](../middlewares/overview.md)
like authentication ([basicAuth](../middlewares/basicauth.md) , [digestAuth](../middlewares/digestauth.md), [forwardAuth](../middlewares/forwardauth.md)) or [whitelisting](../middlewares/ipwhitelist.md).
More information about `api@internal` can be found in the [API documentation](./api.md#configuration)
- Defining one or more security features through [middlewares](../middlewares/overview.md)
like authentication ([basicAuth](../middlewares/basicauth.md) , [digestAuth](../middlewares/digestauth.md),
[forwardAuth](../middlewares/forwardauth.md)) or [whitelisting](../middlewares/ipwhitelist.md).
!!! info "Did You Know?"
The API provides more features than the Dashboard.
To learn more about it, refer to the [API documentation](./api.md)
- Defining your own [HTTP routing rule](../../routing/routers/#rule) for accessing the dashboard,
through Traefik itself (sometimes referred as "Traefik-ception").
Please visit the ["Configuration" section of the API documentation](./api.md#configuration)
to learn about configuring a router with the service `api@internal` and enabling the security features.
## Insecure Mode
This mode is not recommended because it does not allow the use of security features.
To enable the "insecure mode", use the following options from [Traefik's API](./api.md#insecure):
```toml tab="File (TOML)"
[api]
dashboard = true
insecure = true
```
```yaml tab="File (YAML)"
api:
dashboard: true
insecure: true
```
```bash tab="CLI"
--api.dashboard=true --api.insecure=true
```
You can now access the dashboard on the port `8080` of the Traefik instance,
at the following URL: `http://<Traefik IP>:8080/dashboard/` (trailing slash is mandatory).