# Nginx Configuration

{% hint style="info" %}
This page assumes your AthenaBot Dashboard and Web API are already configured and working on local ports.

If you have not finished that yet, complete the Dashboard Setup guide first.
{% endhint %}

## <mark style="color:blue;">Before You Start</mark>

Make sure you know these values before editing Nginx:

* Dashboard domain (example: `panel.example.com`)
* Web API domain (example: `api.example.com`)
* Dashboard local URL (example: `http://127.0.0.1:3222`)
* Web API local URL (example: `http://127.0.0.1:3111`)

Using two subdomains is recommended when transcripts and API routes are served together.

{% hint style="warning" %}
Use different ports for Dashboard and Web API. Do not expose those internal ports directly to the public internet when using Nginx as a reverse proxy.
{% endhint %}

***

## <mark style="color:blue;">HTTP-Only Configuration (Testing)</mark>

Use this only for local testing or private networks.

Create a site file in Nginx (for example `/etc/nginx/sites-available/athena-dashboard`) and add:

```nginx
server {
	listen 80;
	server_name panel.example.com;

	# Dashboard frontend + dashboard API
	location / {
		proxy_pass http://127.0.0.1:3222;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
	}
}

server {
	listen 80;
	server_name api.example.com;

	# AthenaBot Web API + transcripts
	location / {
		proxy_pass http://127.0.0.1:3111;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
	}
}
```

{% hint style="warning" %}
This is a testing-only setup. For production, use HTTPS on both subdomains.
{% endhint %}

***

## <mark style="color:blue;">HTTPS Configuration (Recommended)</mark>

For production, use HTTPS with a valid certificate.

```nginx
server {
	listen 80;
	server_name panel.example.com;
	return 301 https://$host$request_uri;
}

server {
	listen 80;
	server_name api.example.com;
	return 301 https://$host$request_uri;
}

server {
	listen 443 ssl http2;
	server_name panel.example.com;

	ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

	# Dashboard frontend + dashboard API
	location / {
		proxy_pass http://127.0.0.1:3222;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";
	}
}

server {
	listen 443 ssl http2;
	server_name api.example.com;

	ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

	# AthenaBot Web API + transcripts
	location / {
		proxy_pass http://127.0.0.1:3111;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
	}
}
```

***

## <mark style="color:blue;">AthenaBot Config Values When Using Nginx</mark>

Set your Dashboard and Web API URLs in `common.json` to public-facing values:

```json
"dashboard_base_url": "https://panel.example.com",
"web_api_base_url": "https://api.example.com"
```

In your Web API config (`web_api.json(5)`), set `base_ip` to your API domain (example: `api.example.com`).

In Discord Developer Portal OAuth2 redirects, use:

```
https://panel.example.com/api/auth/callback
```

{% hint style="danger" %}
The redirect URL must match exactly, including protocol (`http` or `https`), domain, and path.
{% endhint %}

***

## <mark style="color:blue;">Enable and Test</mark>

After saving your Nginx file:

1. Test syntax:

```bash
sudo nginx -t
```

2. Reload Nginx:

```bash
sudo systemctl reload nginx
```

3. Start AthenaBot and test:

* Open `https://panel.example.com`
* Confirm dashboard login works
* Confirm data loads without `fetch failed`

***

## <mark style="color:blue;">Common Problems</mark>

If the dashboard does not load correctly:

1. `502 Bad Gateway`
   * Dashboard or Web API is not running on the target local port.
   * `proxy_pass` points to the wrong host/port.
2. `fetch failed` or API errors
   * `web_api_base_url` does not match your API subdomain.
   * Web API `authentication_key` is invalid/default.
3. OAuth redirect loop or login failure
   * Redirect URL in Discord Developer Portal does not exactly match the active dashboard URL.
4. Cloudflare / reverse proxy rate-limit issues
   * Set Web API `rate_limit.proxied` to `true`.
   * Keep only trusted proxy paths publicly exposed.