> For the complete documentation index, see [llms.txt](https://theobsidianstudio-1.gitbook.io/theobsidianstudio-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://theobsidianstudio-1.gitbook.io/theobsidianstudio-docs/assets/obs_adminmenu/installation-and-setup.md).

# INSTALLATION & SETUP

{% hint style="success" %}
**Welcome to the OBSIDIAN Ecosystem** You are about to install the most advanced administration framework on the market. Engineered from the ground up for unparalleled performance, our intelligent auto-detection engine guarantees a flawless, zero-configuration setup for 99% of servers.
{% endhint %}

***

### 🏛️ The Obsidian Philosophy

Traditional administration menus are bloated, slow, and prone to breaking during server updates. OBS Admin rewrites the rules. We utilize a highly decoupled, state-of-the-art React architecture running on a `0.00ms` idle footprint. The result is a dashboard that feels indistinguishable from a native desktop application, offering your staff immediate, latency-free control over your community.

***

### 🏗️ 1. Core Dependencies & Footprint

OBS Admin is engineered to be **completely standalone**. We refuse to bloat your server with unnecessary requirements or heavy background loops.

{% tabs %}
{% tab title="Auto-Detect Engine" %}
**Zero Configuration Required**

Our proprietary hook engine actively scans your server's memory upon initialization, natively binding to `ESX`, `QBCore`, `Ox`, and `QS` instantly. You do not need to configure anything—the system automatically maps to your environment and structures its API calls accordingly.
{% endtab %}

{% tab title="Optional Add-ons" %}
While absolutely not required, deploying the following resources will unlock advanced capabilities within the ecosystem:

* **OxMySQL:** Only required if you choose to deploy SQL database synchronization instead of our lightning-fast internal JSON caching system.
* **Ox\_Lib:** Only required if you strictly wish to override our native notifications with standard Ox notifications.
* **Screenshot-Basic:** Required *only* for the high-fidelity Discord Spectate Webhook feature, allowing staff to capture raw framebuffer imagery of suspected cheaters.
  {% endtab %}
  {% endtabs %}

***

### 📥 2. Deployment Protocol

1. Securely download the latest compiled build from your Keymaster portal.
2. Extract the package directly into your server's `resources` directory.

{% hint style="danger" %}
**CRITICAL ARCHITECTURE WARNING** **DO NOT RENAME THE FOLDER.** The resource must remain strictly named `obs_adminmenu`. The React frontend utilizes strict namespace routing. Modifying this folder name will shatter the internal JavaScript NUI callbacks, resulting in a catastrophic UI failure and infinite loading screens.
{% endhint %}

***

### 🗄️ 3. Data Infrastructure & Storage

OBS Admin utilizes a lightning-fast, high-performance JSON architecture by default (`data/bans.json`). This ensures read/write operations complete in microseconds, bypassing the inherent network latency of traditional SQL servers.

{% tabs %}
{% tab title="🚀 Quick Start (Default)" %}
**No Action Required**

If you desire maximum performance with zero setup, your installation is already complete. The system will handle data caching automatically, writing to disk only when necessary to preserve server thread performance. Skip to **Step 4**.
{% endtab %}

{% tab title="💾 SQL Enterprise (Advanced)" %}
If your network requires cross-server synchronization via a centralized SQL database:

1. Open `shared/config.lua`.
2. Toggle `Config.UseMysql = true` and `Config.Report.Database.Enabled = true`.
3. Execute the `install.sql` file into your active database schema to construct the required relational architecture.
   {% endtab %}
   {% endtabs %}

***

### 🛡️ 4. Security Clearance & Authorization

OBS Admin operates on a Zero-Trust security model. You must explicitly authorize your digital identity within the core configuration before the system will allow you to interface with the UI payload.

1. Navigate to `shared/config.lua`.
2. Locate the `Config.Admins` array (around Line 88).
3. Inject your exact identifier (Rockstar License or Discord ID).

```lua
Config.IdentifierType = 'license' -- Options: 'license' or 'discord'

Config.Admins = {
    ['license:YOUR_ROCKSTAR_LICENSE_HERE'] = { rank = 'superadmin', name = 'Your Name' },
}
```

***

### ⚡ 5. Boot Sequence

The startup order in your `server.cfg` is crucial for the hook engine to attach properly. **OBS Admin must boot after your core framework to ensure the environment is fully stabilized.**

```cfg
# ─── CORE INFRASTRUCTURE ───
ensure oxmysql         # (If using SQL)
ensure ox_lib          # (If using Ox_Lib)
ensure screenshot-basic # (If using Screenshots)
ensure qb-core         # (Or es_extended)
ensure ox_inventory    # (Or your preferred inventory)

# ─── OBSIDIAN STUDIO ───
ensure obs_adminmenu
```

***

### 🏁 6. System Diagnostics & Validation

Boot your server. The Obsidian Auto-Detect Engine will execute its pre-flight checks and print a beautiful initialization success message in your console once safely hooked into your memory state.

{% hint style="info" %}
**Interface Hotkeys** Load into your server and utilize the following keys to access the ecosystem:

* **`F10`** - Initialize Web Dashboard
* **`F11`** - Initialize In-Game Overlay
* **`F9`** - Toggle Duty State
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://theobsidianstudio-1.gitbook.io/theobsidianstudio-docs/assets/obs_adminmenu/installation-and-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.