Skip to content

Admin Dashboard

Jump to bottom
Jerad Berhow edited this page Oct 15, 2026 · 11 revisions

Admin Dashboard

A web page where server admins change most of PariahBot's settings for their servers without typing slash commands. The bot's owner sees every server, and how the bot itself is doing. It runs on the machine that runs the bot, and everyone signs in with Discord.

It's off by default.

What you can do in it

Status:

  • the bot's account, how long it's been up, and its Discord latency
  • memory, Node version and the deployed git commit
  • how many servers it's in
  • which integrations are set up (Twitch, YouTube, Instagram, command log channel, and whether the Server-Log shows message text)
  • any RSS feeds that are failing
  • pending temporary bans
  • an invite builder: tick the features you want and it writes an invite link asking for exactly their permissions, with Minimum, Required and Recommended presets matching the links on Bot-Setup

For each server:

Tab Shows Lets you change
General Missing bot permissions, alert channel and DM recipients, member/streamer roles, admin and mod roles All of those
Features Every switchable feature set, whether it is on, and which commands it covers Switch any feature set on or off. See Feature-Switches
Banned words On/off, lists, custom words Turn on/off, pick lists, add/remove words. AutoMod updates straight away
Stream, Instagram & RSS Each feature's channel, ping role, custom message and list All of those, and add/remove streamers, accounts and feeds
Auto-delete Every channel it's on in Set or turn off
Moderation Automatic timeouts, appeal note, temporary bans, the latest 25 cases Automatic timeouts, appeal note, remove a case
Logging Each Server-Log section: on or off, its channel, and anything stopping it (a missing permission, a deleted channel) Pick each section's channel, switch sections on and off
Voice Live temp channels (owner, members, limit, locked), owner controls, every hub and its settings, hubs whose channel was deleted Close or transfer a live channel, switch owner controls, edit/remove/restore hubs, add an existing channel as a hub, create a new hub
Giveaways & more Active giveaways, verification and honeypot, level leaderboard End a giveaway, disable verification or the honeypot

Stays in Discord: setup messages (/security … setup, role menus) and actions against members (/mod). Those need a moderator's judgement, and Discord's own permission checks. Voice is the one area the dashboard creates and deletes channels in: hubs, and closing temp channels.

Every change made in the dashboard is written to the command audit log, as dashboard <action> by you. See Admin-Alerts.

Switched-off features hide their tabs

A feature set switched off for a server (see Feature-Switches) has its tab removed for that server, so the dashboard only offers what is actually running. Where one tab covers several features — Stream, Instagram & RSS, and Giveaways & more — the tab stays while any one of them is on, and only the switched-off parts are left out.

General and Features are always there. Features in particular has to be, since it is the only page that can switch something back on.

Turn it on

With the setup script (recommended)

Run (or re-run) the setup script on the bot's host:

sudo ./deploy/setup.sh               # systemd install
sudo ./deploy/container-setup.sh     # container install

Both ask the same questions. After the bot token and IDs, they ask:

Set up the admin dashboard (a web page for server admins)? [y/N]: y
Dashboard port [8080]:
Discord client secret:
Public address:
  • Port: any free port from 1024 to 65535. 8080 is fine.
  • Client secret: from the Discord Developer Portal → your application → OAuth2 → Client Secret. If none is shown, choose Reset Secret. Treat it like the bot token. It's typed hidden, and pressing Enter on a re-run keeps the current one.
  • Public address: if your admins will reach it from anywhere through a Cloudflare Tunnel, enter its address, e.g. https://pariahbot.yourdomain.com. Leave it blank to use it on the host or through an SSH tunnel. On a re-run, Enter keeps the current address and - clears it.

At the end it prints the exact redirect URL to register (next step), then either the SSH tunnel command for your host or the Cloudflare steps, and how to give your admins access.

Running it again later lets you keep, change or turn off the dashboard. Other settings are left alone.

By hand

Add to /opt/PariahBot/hom.env:

DASHBOARD_PORT=8080
DISCORD_CLIENT_SECRET=your-client-secret

Then sudo systemctl restart pariahbot.service. In the container install the file is /opt/pariahbot-container/hom.env, applied with sudo docker compose up -d in that folder. See Configuration for the two optional overrides.

Register the redirect URL (once)

In the Developer Portal → your application → OAuth2 → Redirects, add exactly:

http://localhost:8080/auth/callback

Use your own port if it isn't 8080. Click Save Changes. Without this, Discord refuses the sign-in with "Invalid OAuth2 redirect_uri".

Check it started

sudo journalctl -u pariahbot.service -n 30     # systemd install
sudo docker logs pariahbot 2>&1 | tail -30     # container install

Look for Dashboard: listening on http://127.0.0.1:8080. If it says Dashboard: … — the dashboard is off, the line says what's missing.

Open it

The dashboard listens on 127.0.0.1 only, so it can't be reached from the network directly.

On the bot's host itself: open http://localhost:8080.

From another computer: open an SSH tunnel to the host, then use your own browser:

ssh -L 8080:localhost:8080 you@your-bot-host

Leave that running, and open http://localhost:8080 on your computer. The tunnel carries it to the bot's host, encrypted. This works the same in Windows PowerShell, macOS and Linux terminals. Close the SSH session to close the tunnel.

Then choose Sign in with Discord, and approve the sign-in. It only asks for your username, nothing else.

Who can sign in, and what they see

Who Sees
The bot's owner: the account that owns the application in the Developer Portal, or every member of its team Every server, plus the Status page
A server admin: Administrator, or an admin role from /setup admin-role, in a server the bot is in Only those servers. No Status page, since it covers every server and the host
A mod (a mod role, but not admin) Nothing: the dashboard reaches /setup, /security and the policy settings, which are admin-only. Mods use the slash commands
Anyone else Nothing. They're turned away at sign-in

Admin is the same rule the admin slash commands use. It's checked again on every page load and change, using the person's roles fetched fresh from Discord. Take away someone's admin role and they lose dashboard access to that server straight away. A session lasts 12 hours, then they sign in again. Every change is in the audit log under the person who made it.

Settings

Variable Default What it does
DASHBOARD_PORT (off) Turns the dashboard on, on this port
DISCORD_CLIENT_SECRET — Needed for Discord sign-in
DASHBOARD_HOST 127.0.0.1 The address it listens on. Leave it alone unless you know you need it
DASHBOARD_PUBLIC_URL http://localhost:<port> The address you open it at, if it isn't that. The redirect URL is this plus /auth/callback

Opening it by name on your network instead

To open it straight from your network as e.g. http://bothost.lan:8080, with no tunnel, set both of these in hom.env and restart:

DASHBOARD_HOST=0.0.0.0
DASHBOARD_PUBLIC_URL=http://bothost.lan:8080

Then register http://bothost.lan:8080/auth/callback as the redirect URL. Discord accepts a plain-http local name like this.

  • Use exactly that address. The dashboard only answers to the name in DASHBOARD_PUBLIC_URL. Opening it by IP address is refused (Unknown host), which stops other websites from reaching it by DNS tricks.
  • The trade-off: anyone on your network can reach the sign-in page, and traffic to it isn't encrypted. Only server admins can get in, but the SSH tunnel, or a Cloudflare Tunnel below, is safer.

Making it public: Cloudflare Tunnel

To let admins reach it from anywhere at an address like https://pariahbot.yourdomain.com, without opening any ports and without their devices getting onto your network, use a Cloudflare Tunnel. A small program on the bot's host connects out to Cloudflare, Cloudflare serves the address over HTTPS, and the only thing visitors reach is the dashboard. It's free, and needs a domain whose DNS is on Cloudflare.

  1. Create the tunnel. In the Cloudflare dashboard, go to Zero Trust → Networks → Tunnels → Create a tunnel. Choose Cloudflared, and name it (e.g. the host's name).
  2. Install it on the bot's host. Pick Debian and your architecture (usually 64-bit). Cloudflare shows a few commands, ending with sudo cloudflared service install <token>. Run them on the host.
    • The token is a secret: run it there, don't paste it anywhere else.
    • It installs as a service that starts at boot.
  3. Add a public hostname:
    • Subdomain pariahbot, and Domain yours.
    • Service: type HTTP, URL localhost:8080, or your DASHBOARD_PORT.
  4. Point the dashboard at it, in hom.env, then restart the bot: 
    DASHBOARD_HOST=127.0.0.1
DASHBOARD_PUBLIC_URL=https://pariahbot.yourdomain.com
    127.0.0.1 keeps it off your network: the tunnel is the only way in. An https address also makes the session cookie secure-only. The setup script's Public address question sets both for you.
  5. Register https://pariahbot.yourdomain.com/auth/callback under OAuth2 → Redirects in the Developer Portal.
  6. Check it: open the address. You should see the sign-in page. Then give your admins access.

Optional second gate: under Zero Trust → Access → Applications, add a self-hosted application for the same hostname, with a policy listing your admins' email addresses. Then the page itself only loads for people Cloudflare has let in, before anyone reaches the Discord sign-in. It's free for up to 50 users.

Giving server admins access

The dashboard has no accounts of its own. Who gets in follows Discord roles, set in each server:

/setup admin-role add role:@Admins
  1. Run that in each server, with the role your admins hold. Any number of admin roles can be added.
  2. Send your admins the dashboard's address. They sign in with Discord, and see only the servers where they're an admin.

Members with Discord's Administrator permission (which includes the server's owner) also get in, with or without the role. Mod roles don't: the dashboard reaches /setup, /security and the policy settings, which are admin-only. See Server-Roles.

Taking the role away removes access straight away, even in an open session.

Security

  • Local only by default: it listens on 127.0.0.1. Remote use goes through your SSH login, or a Cloudflare Tunnel that only reaches the dashboard.
  • Each person sees only the servers they admin, rechecked against their live roles on every request.
  • Sign-in through Discord. The dashboard never sees your password, and only asks for your username. It doesn't keep Discord's access token.
  • Sessions are a signed, HttpOnly cookie, valid for 12 hours. Changing the client secret signs everyone out.
  • Forged requests are refused:
    • changes need the dashboard's own header, from its own page
    • requests for any other host name are refused, which stops a malicious website from talking to it
  • Strict browser security headers: the page can't load outside scripts or be framed by another site.
  • IDs are checked: every channel, role and user the page sends is checked against that server before it's used.
  • Every change is in the audit log.

Troubleshooting

What happens Fix
The page doesn't load Is the SSH tunnel open, on the right port? Does the log show Dashboard: listening?
Cloudflare error page (502 or 1033) at the public address The tunnel can't reach the dashboard. Check systemctl status cloudflared on the host, that the bot is running, and that the public hostname's service is HTTP localhost:<DASHBOARD_PORT>
Unknown host at the public address DASHBOARD_PUBLIC_URL in hom.env isn't that address. Set it, then restart the bot
"Invalid OAuth2 redirect_uri" on Discord Register the redirect URL exactly, port included, and save
"Discord refused the sign-in" The client secret is wrong or was reset. Put the current one in hom.env and restart
"You're not an admin in any server PariahBot is in" That Discord account has no Administrator permission or admin role in any of the bot's servers. A mod role isn't enough. Check you're signed in to the right account in that browser
A server is missing from the list You're not an admin there, by Administrator or an admin role. Ask its owner, or check /setup admin-role list
No Status page That's for the bot's owner only
"That sign-in link expired" You took more than 10 minutes, or opened it twice. Start again from the page
Unknown host You opened it at an address it doesn't know, such as its IP address. Use exactly http://localhost:<port> or your DASHBOARD_PUBLIC_URL
A change fails with a permission message The bot is missing a permission in that server. The General tab lists what's missing
couldn't listen on 127.0.0.1:8080 in the log Something else uses that port. Pick another DASHBOARD_PORT and update the redirect URL

Clone this wiki locally