Installation

Complete the steps in this order. Starting the resource before importing the schema can leave individual applications partially functional and makes the original error harder to identify.

1. Requirements

Required:

• A supported FiveM server artifact.

• oxmysql.

• One supported framework, unless Config.Core is set to standalone.

• A MySQL or MariaDB database supported by your oxmysql version.

Feature-dependent:

• pma-voice for the default call bridge.

• A supported garage, vehicle key, and fuel resource if those phone features are enabled.

• A Fivemanage API token for camera media uploads.

• A Giphy API key for GIF search.

2. Place the resource

Keep the resource folder name exactly src-phone unless every external dependency and export call is updated to use a different name.

resources/
  [phone]/
    src-phone/
      fxmanifest.lua
      install.sql
      client/
      server/
      bridge/
      shared/
      locales/
      web/dist/

The distributed resource uses web/dist/index.html. A source checkout can rebuild the interface from web/, but Node.js is not required on a production server when a valid web/dist is already included.

3. Import the database

Back up the database, then run the complete install.sql file once. The schema uses CREATE TABLE IF NOT EXISTS and additive migrations for supported upgrades.

Do not import only the first few tables. Applications such as MyCloud, wallet, MyFans, Vibe, Wi-Fi, and cellular data depend on tables defined later in the file.

See Database for the table groups and verification queries.

4. Select the framework

Edit shared/config.lua:

Config.Core = 'qbox'

Accepted values:

qb
qbox
esx
vrp
standalone

bridge/config.lua reads this value through BridgeConfig.Framework. Do not configure the two files with different frameworks.

5. Configure integrations

Review bridge/config.lua before the first start:

• BridgeConfig.Garage.GarageSystem

• BridgeConfig.Garage.KeySystem

• BridgeConfig.Garage.FuelSystem

• BridgeConfig.Garage.SQL

• BridgeConfig.Call.VoiceSystem

• BridgeConfig.Services

If your vehicle table does not use the default QB, ESX, or vRP columns, update the SQL mapping before testing Garage or Valet.

6. Configure server-only keys

Set secrets in shared/server_config.lua:

Config.FivemanageApiKey = 'YOUR_FIVEMANAGE_TOKEN'
Config.GiphyApiKey = 'YOUR_GIPHY_API_KEY'

This file is loaded only by the server scripts. Do not move these keys into shared/config.lua, client Lua, the React application, or a public documentation repository. Rotate a token immediately if it has been committed or printed publicly.

7. Start order

Framework and database resources must start before the phone. Voice should also start first when the default call bridge is used.

QBox example:

ensure oxmysql
ensure qbx_core
ensure pma-voice
ensure src-phone

QBCore example:

ensure oxmysql
ensure qb-core
ensure pma-voice
ensure src-phone

ESX example:

ensure oxmysql
ensure es_extended
ensure pma-voice
ensure src-phone

External applications start after src-phone:

ensure src-phone
ensure src-phone-app

An external application should also declare dependency 'src-phone' in its fxmanifest.lua.

8. First-start verification

Verify each item before adding custom integrations:

1. ensure src-phone produces no missing-table or manifest errors.

2. /tel opens and closes the phone.

3. The configured key mapping opens the phone.

4. A character receives a persistent phone number.

5. Contacts and messages survive reconnecting.

6. A second online player can receive a call and message.

7. Camera upload succeeds after a Fivemanage key is configured.

8. Garage records match the configured vehicle table mapping.

9. Wi-Fi or cellular state loads without database errors.

10. Any custom application appears only inside the phone.

Rebuilding the phone UI

Only needed for a source checkout or web modification:

cd src-phone/web
npm install
npm run typecheck
npm run build

Restart src-phone after replacing web/dist.