Skip to content

README.md

Latest commit

 

History

History
236 lines (154 loc) · 6.71 KB

README.md

File metadata and controls

236 lines (154 loc) · 6.71 KB
Raw

FNLB Self-Hosted Deployment 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.

🚀 Prerequisites

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

  • Node.js (version 22 or newer) – Download Node.js
  • A valid FNLB API Token – required to authenticate with FNLB services
  • (Optional) Bun – A fast JavaScript runtime that can be used as an alternative to Node.js
  • (Optional) Docker – Run FNLB in a container without installing Node.js or Bun locally

📦 Installation Steps

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

1. Clone the Repository

Download or clone the FNLB self-hosting project to your local machine:

git clone https://github.com/Fortnite-LobbyBot/Self-Hosted.git
cd Self-Hosted

💡 Alternatively, you can manually copy the files into a folder or download the source code as a ZIP.

2. Install Dependencies

Install required packages with your preferred runtime:

  • Using Node.js:

    npm install

  • Using Bun:

    bun i

3. Configure Environment Variables

Rename the .env.example file to .env:

cp .env.example .env

Edit the .env file with your actual values:

API_TOKEN=your_token_here
CATEGORIES=12345678,98765432
NUMBER_OF_SHARDS=2
BOTS_PER_SHARD=32
RESTART_INTERVAL=3600
CLUSTER_NAME=Self Hosted Cluster

💡 API Token: Obtain this from your FNLB Account under “API Tokens”.
💡 Category IDs: Visit the FNLB Bots Page, select a bot, and locate the “Category ID” in the “About this bot” section.
💡 Bot IDs: Use BOTS alongside CATEGORIES to include specific bots in addition to entire categories. See Bot and category selection below.

▶️ Running the FNLB Cluster

Once configured, start your FNLB instance:

  • With Node.js:

    npm start

  • With Bun:

    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 —
BOTS Comma-separated list of bot IDs to include alongside categories —
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

Omit CATEGORIES and BOTS to start from your full bot pool. Set either or both to limit which bots are eligible.

🎯 Bot and Category Selection

CATEGORIES and BOTS define which bots a shard can pick from. They work as an include list.

  • Categories only - bots in those categories, plus bots without category.
  • Bots only - only the listed bot IDs.
  • Both - bots from the listed categories or the listed bot IDs (union).
  • Neither - your full bot pool.

Invalid category or bot IDs are ignored at startup.

Example: start bots from two categories and two specific bots from elsewhere:

CATEGORIES=category-id-1,category-id-2
BOTS=bot-id-1,bot-id-2

🔄 Keeping FNLB Up to Date

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

  1. Pull the latest changes from the Git repository:

    git pull origin main

  2. Update dependencies:

  • With Node.js:

    npm update fnlb

  • With Bun:

    bun update --latest

  1. Restart the cluster to apply changes:

    npm start
# or with Bun
bun start:bun
# or with Docker
docker compose up -d --build

✅ Regular updates provide access to new features, performance boosts, and essential bug fixes.

🐳 Docker

Run FNLB in a container using the multi-stage Dockerfile.

Prerequisites

Pre-built image

Official images are published to GitHub Container Registry on pushes to the stable branch:

docker pull ghcr.io/fortnite-lobbybot/self-hosted:latest
docker run -d --name fnlb --env-file .env --restart unless-stopped ghcr.io/fortnite-lobbybot/self-hosted:latest

Docker Compose

A docker-compose.yml is included for a simpler workflow. From the project root:

  1. Create and configure your .env file (see above).
  2. Start the cluster in the background:
docker compose pull
docker compose up -d

View logs:

docker compose logs -f

Stop the cluster:

docker compose down

⚙️ 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 and/or specific bot IDs
  • Implements automatic restarts for resilience, using the configured time interval

📎 Additional Resources