# Dashboard Setup

{% hint style="info" %}
Follow this guide from top to bottom.

The Dashboard depends on your Web API config, then your `common.json`, then Discord OAuth.
{% endhint %}

{% hint style="danger" %}
**Stop the bot before continuing.**

Changing dashboard or API values while AthenaBot is running can cause startup issues and stale cache values.
{% endhint %}

## <mark style="color:blue;">AthenaBot Web API Setup</mark>

The Web API is the bridge between AthenaBot and the Dashboard. If this is wrong, the dashboard will not load data.<br>

Open <mark style="color:green;">**`/configuration/web_api.json(5)`**</mark> and complete these steps:

#### <mark style="color:orange;">1. Set your API port</mark>

Pick a free port (example uses `3111`):

```json5
port: "3111"
```

#### <mark style="color:orange;">2. Set a secure authentication key</mark>

Replace the default value in `authentication_key`:

```json5
authentication_key: ["your-super-secure-key"]
```

{% hint style="danger" %}
Leaving the default API key is unsafe and can break plugin startup checks.
{% endhint %}

#### <mark style="color:orange;">3. Set base IP / domain</mark>

Configure `base_ip` as one of the following:

* `"<host_ip>:<web_api_port>"` (IP/port setup)
* `"<domain>"` (domain setup)

#### <mark style="color:orange;">4. Optional hardening options</mark>

* `secure_mode`: set `true` to limit most API routes to `whitelisted_ips`.
* `whitelisted_ips`: keep required defaults and add trusted sources.
* `rate_limit.enabled`: keep enabled for protection.
* `rate_limit.proxied`: set `true` if you are behind Nginx/Apache/Cloudflare.

***

## <mark style="color:blue;">Dashboard Configuration</mark>

Now open <mark style="color:green;">**`/common.json`**</mark> and edit the `dashboard` section.

#### <mark style="color:orange;">1. Enable dashboard</mark>

```json
"enabled": true
```

#### <mark style="color:orange;">2. Set dashboard port</mark>

```json
"port": 3222
```

Use a different port than Web API.

#### <mark style="color:orange;">3. Configure both URLs</mark>

Dashboard URL:

```json
"dashboard_base_url": "http://<host_ip>:<dashboard_port>"
```

or

```json
"dashboard_base_url": "https://<domain>"
```

Web API URL:

```json
"web_api_base_url": "http://<host_ip>:<web_api_port>"
```

#### <mark style="color:orange;">4. Whitelist your Discord account</mark>

Add your Discord user ID to:

```json
"whitelisted_user_ids": ["YOUR_DISCORD_USER_ID"]
```

#### <mark style="color:orange;">5. Review optional dashboard flags</mark>

* `disable_dashboard_configuration`: set `true` to disable config editing from the panel. The bot will use the configuration files in `/configuration` instead.
* `sync_dashboard_configs_to_file`: set `true` to sync DB changes back into `/configuration` files.

{% hint style="warning" %}
Any changes made in the dashboard are not automatically written to the bot configuration files in `/configuration`. The dashboard stores settings in the database, and while the dashboard is enabled, those database values override values from config files.

If you want dashboard settings to be written back into config files, enable `sync_dashboard_configs_to_file` in `common.json`. Enabling this can overwrite your existing configuration files. This synchronization is one-way only: dashboard -> file.

If you want to reset dashboard settings and restore values from configuration files, run this command while the bot is running:

`script clear-dashboard`
{% endhint %}

{% hint style="warning" %}
This system is still in BETA, so use it carefully.
{% endhint %}

***

## <mark style="color:blue;">Discord OAuth Setup</mark>

The dashboard login uses Discord OAuth.

#### <mark style="color:orange;">1. Add redirect URL</mark>

Open your app in the Discord Developer Portal:

* <https://discord.com/developers/applications>
* Go to `OAuth2` -> `Redirects`

Add one of these:

* `http://<host_ip>:<dashboard_port>/api/auth/callback`
* `https://<domain>/api/auth/callback`

#### <mark style="color:orange;">2. Add client secret to common.json</mark>

Reset/copy your Discord Client Secret and set:

```json
"discord_client_oauth_secret": "YOUR_NEW_DISCORD_CLIENT_SECRET"
```

***

## <mark style="color:blue;">Final Checklist</mark>

* [ ] <mark style="color:purple;">**Stop the bot**</mark> before editing config.
* [ ] <mark style="color:purple;">**Web API configured**</mark> (`port`, `authentication_key`, `base_ip`).
* [ ] <mark style="color:purple;">**Dashboard configured**</mark> (`enabled`, `port`, base URLs, whitelist IDs).
* [ ] <mark style="color:purple;">**OAuth redirect added**</mark> in Discord Developer Portal.
* [ ] <mark style="color:purple;">**OAuth secret added**</mark> to `common.json`.
* [ ] <mark style="color:purple;">**Restart AthenaBot**</mark> and open your panel URL.

{% hint style="success" %}
If login works and dashboard cards/pages load, your setup is complete.
{% endhint %}

***

## <mark style="color:blue;">Dashboard Errors</mark>

If you hit errors like `fetch failed`, `Unexpected token '<'`, API status errors, or redirect loops:

1. Confirm `authentication_key` is not default and is valid.
2. Confirm dashboard and API ports are different and reachable.
3. Confirm `dashboard_base_url` and `web_api_base_url` are correct.
4. Confirm OAuth redirect URL exactly matches your dashboard URL.
5. Confirm your Discord ID is included in `whitelisted_user_ids`.
6. If proxied, confirm `rate_limit.proxied` is configured correctly.