> ## Documentation Index
> Fetch the complete documentation index at: https://developer-docs.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting Guide

> Easily self-host your own FNLB cluster using this minimal setup. FNLB is a powerful and scalable system for managing Fortnite bots at scale.

<Card title="View GitHub Repository (optional)" icon="github" horizontal href="https://github.com/Fortnite-LobbyBot/Self-Hosted">
  Browse the full source code, issues, and updates on GitHub
</Card>

## Prerequisites

Before you begin, make sure you have the following installed and ready:

* **Node.js** (version 22 or newer) – [Download Node.js](https://nodejs.org/)
* A valid [**FNLB API Token**](https://app.fnlb.net/account) – required to authenticate with FNLB services. [Learn more.](/authenticating)
* *(Optional)* [**Bun**](https://bun.sh) – A fast JavaScript runtime that can be used as an alternative to Node.js

***

## Installation Steps

Follow these steps to get your FNLB cluster up and running:

<Steps>
  <Step title="Clone the Repository">
    Download or clone the FNLB self-hosting project to your local machine:

    ```bash theme={null}
    git clone https://github.com/Fortnite-LobbyBot/Self-Hosted.git
    cd Self-Hosted
    ```

    <Info>
      **Alternatively**, you can manually copy the files into a folder or [download the source code](https://github.com/Fortnite-LobbyBot/Self-Hosted/archive/refs/heads/dev.zip) as a ZIP.
    </Info>
  </Step>

  <Step title="Install Dependencies">
    Install required packages with your preferred runtime:

    * Using **Node.js**:

      ```bash theme={null}
      npm install
      ```
    * Using **Bun**:

      ```bash theme={null}
      bun i
      ```
  </Step>

  <Step title="Configure Environment Variables">
    Rename the `.env.example` file to `.env`:

    ```bash theme={null}
    cp .env.example .env
    ```

    Edit the `.env` file with your actual values:

    ```ini theme={null}
    API_TOKEN=your_token_here
    CATEGORIES=12345678,98765432
    NUMBER_OF_SHARDS=2
    BOTS_PER_SHARD=32
    RESTART_INTERVAL=3600
    CLUSTER_NAME=Self Hosted Cluster
    ```

    <Info>
      **API Token:** Get this from your [FNLB Account](https://app.fnlb.net/account) under “API Tokens”.
    </Info>

    <Info>
      **Category IDs:** Visit the [FNLB Bots Page](https://app.fnlb.net/bots), select a bot, and locate the **“Category ID”** in the **“About this bot”** section.
    </Info>
  </Step>
</Steps>

## Running the FNLB Cluster

Once configured, start your FNLB instance:

* With **Node.js**:

  ```bash theme={null}
  npm start
  ```
* With **Bun**:

  ```bash theme={null}
  bun start:bun
  ```

The cluster will initialize using your configuration and automatically restart on the interval you defined, ensuring long-term stability and uptime.

***

## Environment Variable Reference

Below is a breakdown of each environment variable used in the setup:

| Variable           | Description                                                     | Default               |
| ------------------ | --------------------------------------------------------------- | --------------------- |
| `API_TOKEN`        | Your personal FNLB API token                                    | *Required*            |
| `CATEGORIES`       | Comma-separated list of bot category IDs                        | *Required*            |
| `NUMBER_OF_SHARDS` | Number of individual shards (instances) to spawn                | `2`                   |
| `BOTS_PER_SHARD`   | Maximum number of bots assigned to each shard                   | `32`                  |
| `RESTART_INTERVAL` | Cluster restart interval in seconds (for stability/maintenance) | `3600`                |
| `CLUSTER_NAME`     | The name of the cluster that will appear in the app             | `Self Hosted Cluster` |

***

## Keeping FNLB Up to Date

Ensure you're always using the latest and most stable version of FNLB:

<Steps>
  <Step title="Pull the latest changes from the Git repository">
    ```bash theme={null}
    git pull origin main
    ```
  </Step>

  <Step title="Update dependencies">
    * With **Node.js**:

      ```bash theme={null}
      npm update fnlb
      ```
    * With **Bun**:

      ```bash theme={null}
      bun update --latest
      ```
  </Step>

  <Step title="Restart the cluster to apply changes">
    ```bash theme={null}
    npm start
    # or
    bun start:bun
    ```
  </Step>
</Steps>

<Tip>
  Regular updates provide access to new features, performance boosts, and essential bug fixes.
</Tip>

***

## What the Script Does

Once started, the script performs the following:

* Initializes FNLB using your API credentials and environment settings
* Configures:
  * Number of **shards** (isolated bot processes)
  * Maximum **bots per shard**
  * Allowed **category IDs**
* Implements automatic restarts for resilience, using the configured time interval

***

## Troubleshooting

If you encounter issues while setting up or running your FNLB cluster, check the following common solutions:

### `Invalid API Token` Error

* **Cause**: The `API_TOKEN` in your `.env` file is incorrect or has been revoked.
* **Solution**: Double-check your token in the [FNLB Dashboard](https://app.fnlb.net/account). Ensure there are no leading or trailing spaces.

### Shards Crashing on Startup

* **Cause**: Insufficient system resources (RAM/CPU) or Node.js version mismatch.
* **Solution**: Ensure you are using **Node.js 22+**. If running many shards, monitor your memory usage. Try reducing `NUMBER_OF_SHARDS` to test.

### Connection Issues

* **Cause**: Network connectivity issues.
* **Solution**: Ensure your server has outbound access to `api.fnlb.net` and `gateway.fnlb.net`.

***

## 📎 Additional Resources

* [FNLB Official Site](https://fnlb.net)
* [FNLB Dashboard](https://app.fnlb.net)
* [FNLB Documentation](https://docs.fnlb.net)

## 🗨️ Join the Community

Need help, support, or just want to chat with other developers?

Come hang out with us on Discord! 👇

<Card title="Join Discord" icon="discord" href="https://fnlb.net/discord">
  Get help, support, or chat with other developers
</Card>