> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/getting-started/dashboard-setup.md).

# Dashboard Setup

{% hint style="warning" %}
**This setup guide assumes that the** [**Basic Setup Guide**](/getting-started/basic-setup-guide.md) **has already been completed!**
{% endhint %}

{% hint style="info" %}
We've recorded a **video** that walks you through this part of the documentation. [Check it out here](https://www.youtube.com/watch?v=31lCDLs6b3s)!
{% 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 cannot 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 of `authentication_key` with a randomly generated string:

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

{% hint style="danger" %}
Leaving the **default API key** unchanged will prevent the plugin from loading for security reasons.
{% endhint %}

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

Configure `base_ip` using **one** of the following options:

* IP Address: `"<host_ip>:<web_api_port>"`\
  Example: `123.123.123.123:3111`
* Domain: `"<web_api_subdomain>"`\
  Example: `api.iynxdev.com`

{% hint style="info" %}
If you are using a domain, point it to your server using an **A record** (or **CNAME**) and configure either a **reverse proxy** (recommended) or **Cloudflare Tunnel** to forward requests to your dashboard. DNS and web server configuration are outside the scope of this guide.
{% endhint %}

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

* `secure_mode`: Restrict most API routes to trusted IP addresses listed in `whitelisted_ips`
* `whitelisted_ips`: Keep the default entries and add any additional trusted IP addresses that should be allowed to access protected API routes
* `rate_limit.enabled`: Keep enabled to protect the API against excessive requests
* `rate_limit.proxied`: Enable if the dashboard is behind a reverse proxy (e.g. Nginx, Apache, Caddy, or Cloudflare Tunnel)

***

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

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

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

{% hint style="warning" %}
The dashboard must use a **different** port than the one configured for the Web API
{% endhint %}

#### <mark style="color:orange;">3. Configure the Dashboard & Web API URLs</mark>

Update both URLs to match your deployment.

**Dashboard URL (`dashboard_base_url`):**

* IP setup: `http://<server_ip>:<dashboard_port>`\
  Example: `http://123.123.123.123:3222`
* Domain setup: `https://<dashboard_subdomain>`\
  Example: `https://dashboard.iynxdev.com`

\
**Web API URL (`web_api_base_url`):**

* IP setup: `http://<server_ip>:<web_api_port>`\
  Example: `http://123.123.123.123:3111`
* Domain: *equals IP setup*

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

Add your Discord user ID to:

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

#### <mark style="color:orange;">5. Optional Dashboard Configuration</mark>

When the dashboard is enabled for the first time, Athena imports the configuration files from the `/configuration` directory into the database.

From that point onward, **the dashboard configuration becomes the source of truth**. Changes made to the configuration files are ignored while the dashboard is enabled.

Optional settings:

* **`disable_dashboard_configuration`:** Prevent configuration changes from the dashboard and use the configuration files in `/configuration` instead.
* **`sync_dashboard_configs_to_file`:** Automatically write configuration changes made in the dashboard back to the files in `/configuration`.

{% hint style="warning" %}
Enabling `sync_dashboard_configs_to_file` **may overwrite** your existing configuration files. <br>

Synchronization only occurs from the dashboard to the configuration files, **not the other way around**.
{% endhint %}

{% hint style="info" %}
If you want to **discard** the dashboard configuration and **reimport** your configuration files, run in console while the bot is running:

```
script clear-dashboard
```

{% 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 application in the [**Discord Developer Portal**](https://discord.com/developers/applications) and navigate to **OAuth2 → Redirects**.

Add **one** of the following redirect URLs:

* **IP setup:** `http://<host_ip>:<dashboard_port>/api/auth/callback`\
  Example: `http://123.123.123.123:3222/api/auth/callback`
* **Domain setup**: `https://<dashboard_subdomain>/api/auth/callback`\
  Example: `https://dashboard.iynxdev.com/api/auth/callback`

#### <mark style="color:orange;">2. Configure the Client Secret</mark>

In the **Discord Developer Portal**, navigate to **OAuth2**, generate or copy your **Client Secret**, and set it in `common.json`:

```json
"discord_client_oauth_secret": "YOUR_DISCORD_CLIENT_SECRET"
```

***

{% hint style="success" %}
**Setup Complete!**

Restart the bot and access your dashboard using the URL you configured:

* **IP setup:** `http://<server_ip>:<dashboard_port>`\
  Example: `http://123.123.123.123:3222`
* **Domain setup:** `https://<dashboard_subdomain>`\
  Example: `https://dashboard.iynxdev.com`
  {% endhint %}