Installation & Usage

The portal is off until you finish this page, and it fails shut - a half-finished setup serves a bare 404 rather than a login page that cannot complete.

Budget about 20 minutes. You need three things before you start:

• a domain you own
• a free Cloudflare account
• a Discord server you can administrate

Only the last of those is needed to try it on your own machine first - see Testing without a domain.

Step 1 - Create a Discord application

This gets you two of the five values.

Step 2 - Get your Discord server ID

1. Discord → User Settings → Advanced → turn on Developer Mode.
2. Right-click your server's icon in the sidebar → Copy Server ID.

That 18-digit number is xt_admin_discord_guild.

Step 3 - Put the portal on an https hostname

Discord will only redirect to https://, and FXServer has no TLS of its own - it serves this resource in plaintext on the game port, which is already open to the internet on every live server. A Cloudflare Tunnel gives you the hostname and the certificate, for free, without opening anything further: cloudflared on your server dials out to Cloudflare, and Cloudflare hands the portal's requests back down that connection.

There are two ways to set one up. Use the dashboard unless you already run tunnels from a config.yml - it is the same tunnel, with the routing rule and the service install done for you, and nothing to keep in a file on the box.

# the last line the dashboard gives you - the token is the long string
cloudflared.exe service install <TOKEN>        # Windows
sudo cloudflared service install <TOKEN>       # Linux

admin.yourdomain.com is your xt_admin_portal_host.

Because cloudflared forwards the path exactly as it received it, the portal lives under /xt-adminportal - so you also set xt_admin_portal_base "/xt-adminportal". Only if you put nginx or Caddy in front and rewrite that prefix away do you leave portal_base unset.

Step 4 - Fill in server.cfg

Put these above your ensure lines - convars are read when the resource starts.

set xt_admin_portal_host    "admin.yourdomain.com"    # Step 3
set xt_admin_portal_base    "/xt-adminportal"         # Step 3 - Cloudflare Tunnel setups need this
set xt_admin_discord_id     "1234567890123456789"     # Step 1
set xt_admin_discord_secret "xxxxxxxxxxxxxxxxxxxx"    # Step 1
set xt_admin_discord_guild  "9876543210987654321"     # Step 2

ensure xt-admin          # the menu - owns every permission decision the portal makes
ensure xt-adminportal    # the portal - must come after it

Starting xt-adminportal first is survivable - it waits for xt-admin and refuses to serve anything until it answers. Starting it without xt-admin means a console error and a portal that 404s every request.

Step 5 - Turn it on and read the console

enabled = true,

Restart the server. The console prints two lines:

Web portal ready at https://admin.yourdomain.com/xt-adminportal/
Web portal: set the Discord redirect URI to https://admin.yourdomain.com/xt-adminportal/auth/callback

Copy that second URL into your Discord application → OAuth2 → Redirects → Save. It has to match character for character, trailing slash and all.

Step 6 - Give your staff a rank

Use one of these instead. All three live in xt-admin, not here - ranks are its business, and the portal only asks.

Grant by Discord role

You almost certainly already have @Moderator and @Admin roles, and staff changes then happen entirely in Discord: hand someone the role and they have the portal on their next login, take it away and they are out. Nobody has to edit a config or log into the game to promote a new moderator. Map each role once -

permissionsByDiscordRole = {
    [123456789012345678] = 'mod',     -- @Moderator
    [987654321098765432] = 'admin',   -- @Admin
},

The other two

Both are keyed on a license, and Discord hands the portal no license at all - so the Discord account has to be matched back to one out of your own database. That happens automatically for anyone currently connected, anyone previously banned, and - via the discordToLicense hook in xt-admin/configs/server.lua - anyone in QBX's users table, which records license, license2, fivem and discord side by side on first connect.

Step 7 - First login

Lost phone? In game: Settings tab → Web Portal → the 2FA button next to their name clears their enrolment and signs them out, so they re-enrol on the next login.

Configuration

Everything that is not a secret lives in configs/portal.lua.

-- Master switch. Nothing is reachable while this is false.
enabled = true,

-- Discord role ids a member must have before they can even try to log in.
-- Empty means any guild member may try (they still need an admin rank to get in).
requiredGuildRoles = {},

session = {
    idleMinutes   = 60,    -- minutes of inactivity before a session ends. Any request resets it
    absoluteHours = 12,    -- hours a session can live in total, however active
    bindUserAgent = true,  -- tie a session to the browser it was created in
},

totp = {
    required = true,       -- ask for an authenticator code at login. Leave this on
    issuer   = 'xT Admin', -- the name shown in the authenticator app
    window   = 1,          -- 30-second steps of clock drift to accept. 1 for phones, 2 max
},

-- Watch a player's screen from the browser. OFF by default and a separate
-- decision from `enabled`. Staff also need the `portalViewScreen` permission
-- in xt-admin. Frames are never saved anywhere.
screens = false,

-- Requests allowed per minute, per IP address.
rateLimit = {
    apiPerMinute    = 120,   -- normal portal traffic
    authPerMinute   = 10,    -- login and code entry. Kept low so a 6-digit code cannot be guessed
    tilePerMinute   = 600,   -- map tiles. One pan loads many at once, and the browser caches them
    screenPerMinute = 240,   -- screen-view polling. Ignored while `screens` is false
},

-- Behind Cloudflare Tunnel or a reverse proxy, use CF-Connecting-IP /
-- X-Forwarded-For as the visitor's address for rate limiting.
trustProxyHeader = true,

-- Largest request body accepted, in kilobytes. Saving the economy map has its
-- own, larger allowance and ignores this.
maxBodyKb = 64,

Day-to-day usage

Kill switch. Admin menu → Settings → Web Portal → Revoke all. Every session dies immediately, including any live screen view.

Demoting someone. Change their rank in game and it takes effect on their next click. You do not need to revoke their session - though revoking is instant and costs nothing.

Reading the logs. Portal actions are marked via = portal in the same audit trail as the in-game ones. Nothing is filed in a separate place.

Testing without a domain

For trying the panel out on your own machine. Not a deployment. If you do this on a box whose game port is forwarded, the handler is still reachable out there - what stops a stranger is that every URL the portal builds points at localhost, so the Discord round-trip lands on their machine and no session is ever issued. That is a side effect of the loopback host, not a security boundary: keep it to a dev box, and put totp.required back before the host convar becomes a real hostname.

You still need Steps 1 and 2: a Discord application and your guild id. There is no way around those, and no bot is involved.

set xt_admin_portal_host    "localhost:30120"
set xt_admin_portal_base    "/xt-adminportal"
set xt_admin_discord_id     "<application id>"
set xt_admin_discord_secret "<client secret>"
set xt_admin_discord_guild  "<guild id>"

ensure xt-admin
ensure xt-adminportal

Web portal ready at http://localhost:30120/xt-adminportal/
Web portal: set the Discord redirect URI to http://localhost:30120/xt-adminportal/auth/callback

permissionsByDiscordRole = {
    [123456789012345678] = 'dev',   -- right-click your role in Discord → Copy Role ID
},