Skip to main content

View GitHub Repository (optional)

Browse the full source code, issues, and updates on GitHub

​
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. Learn more.
  • (Optional) Bun – 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:
1

Clone the Repository

Download or clone the FNLB self-hosting project to your local machine:
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:
  • Using Bun:
3

Configure Environment Variables

Rename the .env.example file to .env:
Edit the .env file with your actual values:
API Token: Get 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.

​
Running the FNLB Cluster

Once configured, start your FNLB instance:
  • With Node.js:
  • With 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:

​
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

2

Update dependencies

  • With Node.js:
  • With Bun:
3

Restart the cluster to apply changes

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

​
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. 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

​
🗨️ Join the Community

Need help, support, or just want to chat with other developers? Come hang out with us on Discord! 👇

Join Discord

Get help, support, or chat with other developers