> For the complete documentation index, see [llms.txt](https://docs.sourcedev.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sourcedev.pro/src-phone/installation.md).

# 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](/src-phone/database.md) for the table groups and verification queries.

## 4. Select the framework

Edit `shared/config.lua`:

```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`:

```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:

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

QBCore example:

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

ESX example:

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

External applications start after `src-phone`:

```cfg
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:

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

Restart `src-phone` after replacing `web/dist`.