Installation Guide

This guide walks server owners and administrators through installing the ars_cardealer resource. The resource supports QBCore, QBox, and ESX, and includes a prebuilt NUI — no frontend build tools are required.

Prerequisites

Before installing, ensure the following resources are running on your server:

Resource	Purpose	Required
oxmysql	Database layer (parameterized queries)	Yes
ox_lib	UI library, callbacks, locales, notifications	Yes
screenshot-basic	Vehicle image capture feature	Yes
qb-core / qbx_core / es_extended	Game framework	Yes (one)
ox_target / qb-target / qtarget	World/entity interaction	Yes

Note: A target resource is mandatory. The dealership catalog opens only by targeting the salesman ped — there is no command, keybind, or marker fallback to browse vehicles.

Installation Steps

1. Download and Place Resource

• Download the resource from portal.cfx.re
• Place the folder in your server’s resources directory:

server-data/resources/[folder]/ars_cardealer/

The NUI frontend (html/) is prebuilt and included in the download. No build step is required.

2. Configure Framework

In config.lua, set or verify the framework detection:

Config.Framework = 'auto' -- 'auto' | 'qb' | 'qbx' | 'esx'

With 'auto', the resource detects QBox, QBCore, or ESX on startup. To force a specific framework, set it explicitly.

The target resource is auto-detected by default:

Config.Target = 'auto' -- 'auto' | 'ox' | 'qb' | 'qtarget'

3. Configure Admin Access

Set who can access the admin panel in config.lua:

Config.Admin = {
    openCommand = 'arscardealer',
    auditRetentionDays = 90,

    allow = {
        group = {
            ['admin'] = true,
            ['god']   = true,
        },
        license = {
            -- ['license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] = true,
        },
        identifier = {
            -- ['xxxxxxxx'] = true,
        },
    },
}

A player is an admin if they match any allow-list entry. Leave a table empty to disable that method.

4. Add to Server Config

Add the following to your server.cfg, ensuring ensure order is correct:

ensure oxmysql
ensure ox_lib
ensure screenshot-basic
ensure [framework]     -- qb-core, qbx_core, or es_extended
ensure [target]        -- ox_target, qb-target, or qtarget
ensure ars_cardealer

5. Database Setup

No manual SQL import is needed on a fresh database. The schema in sql.sql is applied automatically on resource start by server/boot.lua using idempotent CREATE TABLE IF NOT EXISTS statements.

Note: Upgrading from an older build: sql.sql is the canonical target schema only — it contains no migration statements, and existing tables are never altered. If you are updating from a release older than v1.1.0, drop the old ars_cardealer_* tables and re-import sql.sql (or apply the new columns by hand), then restart the resource.

If you prefer to run the SQL manually, sql.sql is safe to execute directly on your database.

6. Configure Vehicle Image Uploads

Catalog image capture (single and bulk) takes a screenshot via screenshot-basic, removes the green screen in the NUI, then uploads the PNG to an image host. The host is picked in server/utils.lua — not in config.lua, because webhook URLs and API keys are secrets that must never ship to clients:

-- server/utils.lua
local uploadProvider = 'discord'

local uploadProviders = {
    wew        = { url = 'https://wew.wtf/upload.php',             field = 'files[]' },
    fivemanage = { url = 'https://api.fivemanage.com/api/v3/file', field = 'file', apiKey = '' },
    fivemerr   = { url = 'https://api.fivemerr.com/v1/media/images', field = 'file', apiKey = '' },
    discord    = { webhook = '', field = 'files[]' },
}

Provider	What to fill in	Notes
discord (default)	Paste your own channel webhook URL into discord.webhook	Create it under Server Settings → Integrations. Ships empty, so capture fails until you set it.
fivemanage	Paste your API key into fivemanage.apiKey	Sent as the Authorization header to https://api.fivemanage.com/api/v3/file.
fivemerr	Paste your API key into fivemerr.apiKey	Sent as the Authorization header to https://api.fivemerr.com/v1/media/images.
wew	Nothing — works with the defaults	Uploads to https://wew.wtf/upload.php.
custom	Add your own entry and branch on it inside Server.GetUploadConfig()	See the comment above Server.GetUploadConfig() in server/utils.lua.

Warning: Never commit a real webhook URL or API key to a public repo — anyone with the URL can post to the channel. server/utils.lua is buyer-editable (escrow_ignore), so edit it directly on the server.

To verify: restart the resource and check the server console. A misconfigured provider prints vehicle_images: upload provider "..." misconfigured (...) at boot — fix the values in server/utils.lua until that warning is gone, then run one test capture from the admin Catalog tab.

Verification

1. Start your server and ensure ars_cardealer loads without errors in the console.
2. If the framework was not detected, the server console prints a startup error — fix it by setting Config.Framework explicitly ('qb', 'qbx', or 'esx') in config.lua. With Config.Debug = true, a successful boot also prints server ready (framework: ...).
3. Join the game as an admin (matching Config.Admin.allow) and run /arscardealer — the admin panel should open.
4. Approach a dealership’s salesman ped and target it — the browse UI should open.
5. Run /myfinance — your financing panel should open.

Updating

1. Replace the resource folder with the new version.
2. Restart the resource in-game.

New tables apply automatically via CREATE TABLE IF NOT EXISTS — existing tables are never altered. If the new version adds columns to an existing table, re-import sql.sql (or apply the new columns by hand); see the note under Database Setup.

Troubleshooting

No target resource detected

If the server console prints warnings about no target resource:

• Ensure ox_target, qb-target, or qtarget is started in server.cfg.
• Verify Config.Target is set to 'auto' or the correct target name in config.lua.

Admin panel does not open

• Verify your account matches one of the Config.Admin.allow lists (group, license, or identifier).
• Check the server console for no_permission messages.

Framework not detected

• If Config.Framework = 'auto' shows “No framework detected”, set it explicitly to 'qb', 'qbx', or 'esx' in config.lua.
• Ensure your framework resource is started before ars_cardealer in server.cfg.

Image capture fails or returns no URL

• Check the server console at boot for vehicle_images: upload provider "..." misconfigured (...) — the active provider in server/utils.lua is missing its webhook URL or API key. See Configure Vehicle Image Uploads.
• Verify screenshot-basic is started before ars_cardealer in server.cfg.
• Verify Config.ImageCapture.enabled is true in config.lua.

SQL errors on startup

• Verify oxmysql is running and connected to your database.
• The schema uses CREATE TABLE IF NOT EXISTS — existing tables are never overwritten.

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.