Unifier
Install guide for Unifier v3.0.0 and newer.
This guide is for Unifier v3.0.0 and newer. If you're installing an older version of Unifier, consult the legacy guide instead.
Used the Installer?
Unifier cannot be installed using the legacy installer. Please use the integrated installer instead.
Requirements
Minimum system requirements
Memory requirements will depend on many factors such as but not limited to cached messages and number of servers the bot is in.
Unifier requires the following:
64-bit CPU that can run Python 3.9 or newer
At least 100MB of available RAM, meaning excluding RAM already being used by the system and other apps
An internet connection
Python 3.9 or newer
Right now, Optimized does not require any additional requirements, but it may require Python 3.12 or newer in the future. Check here for more info.
Recommended system requirements
We recommend the following for Unifier:
64-bit CPU based on x86_64 or arm64/aarch64 that can run Python 3.11 or newer
20 Mbps or faster internet connection
Python 3.12 or newer
Running Unifier
To run or install Unifier, you will need to launch the "bootloader". The bootloader checks if there is already a Unifier installation present before starting Unifier, otherwise it will run the installer.
Self-hosted
On Linux, macOS, or any other compatible systems that use bash, run ./run.sh. We recommend you run this in a screen, so Unifier can keep running even after you close the terminal or SSH session to your host server.
On Windows, run ./run.bat.
Managed (Pterodactyl)
Pterodactyl containers run on top of a Linux system, meaning that it can run bash programs. However, some Eggs might not support this, and may restrict you to running Python files only.
If you can customize the startup command, set it to sh run.sh.
If you can customize the "App PY file" field, set it to boot/bootloader.py.
Start the server once one of the above have been set.
Installing Unifier
From v3.0.0, the integrated installer automatically handles installing dependencies.
Your console should output the following if no Unifier installation has been detected, after asking you which installation option you would like:
For most cases, you should choose Optimized for the best performance, as it includes the latest version of Nextcord and additional libraries (such as but not limited to Brotli, aiodns, ujson) for performance optimization. However, if this option causes issues, or you want maximum stability, you should choose Stable.
To choose an installation option, type its corresponding option number, then press enter. After you have chosen the installation option, you should get the following:
Type "y" to install Unifier, then follow the instructions provided by the installer. After installation is complete, Unifier will automatically start.
Using System Manager
WARNING: Do NOT grant anyone access to admin commands! Certain admin commands have the potential to ruin your system if used maliciously!
We STRONGLY ENCOURAGE you to NOT modify System Manager whatsoever for this very reason.
Unifier has a powerful System Manager to let instance owners effortlessly run commands and manage extensions.
Here's some basic commands to get you started:
u!reload <extension>: Reloads an extension, useful for updating extensions without restarting the entire bot.u!eval <command>: Evaluates a Python command. Only use if you know what you're doing!u!install <plugin>Installs a plugin from a Git repository. A valid plugin.json file is required.u!uninstall <plugin>: Uninstalls a plugin.u!upgrade [plugin] [args]: Upgrades a plugin. If all arguments are left empty, it will upgrade Unifier.u!shutdown: Shuts the bot down.u!reboot: Reboots the bot.
Further setup
Installing Revolt Support
"Revolt Support" references the Unifier Revolt Support extension, not the Revolt support team.
First, you will need to create a Revolt bot, then add its token to the .env file as TOKEN_REVOLT, as well as the user IDs of admins as admin_ids. As Unifier's admins list allow both integers and strings, you can have both Discord and Revolt users under the same list. Then, you will need to enable Revolt as an external service by adding revolt to the externals list. So your config.json and .env file should look something like this:
As Revolt uses alphanumeric IDs, rather than integers, you will need to save admin IDs as strings.
Then, you will need to reboot the bot so the new configuration can be read by the extension. You can then run u!install https://github.com/UnifierHQ/unifier-revolt to install Revolt Support.
Misconfiguration, such as a missing Revolt bot token, will result in the upgrade failing. This is caused by the System Manager being unable to start Revolt Support, and in most cases can be fixed by running u!load bridge_revolt. If this does not help, run u!restart.
If all goes well, Revolt Support will be running and your Revolt bot will be up and running. You can always stop Revolt Support by running u!stop-revolt.
Alternatively, you can also run u!unload bridge_revolt to stop Revolt Support.
If you wish to stop Revolt Support from loading on boot, please uninstall the Plugin. All dependencies and configuration files will be retained.
Installing Guilded Support
"Guilded Support" references the Unifier Guilded Support extension, not the Guilded support team.
As Guilded Support is programmed similarly to Revolt Support, the installation process is near identical.
First, you will need to create a Guilded bot, then add its token to the .env file as TOKEN_GUILDED, as well as the user IDs of admins as admin_ids. As Unifier's admins list allow both integers and strings, you can have both Discord and Guilded users under the same list. Then, you will need to enable Revolt as an external service by adding guilded to the externals list. So your config.json and .env file should look something like this:
As Guilded uses alphanumeric IDs, rather than integers, you will need to save admin IDs as strings.
Then, you will need to reboot the bot so the new configuration can be read by the extension. You can then run u!install https://github.com/UnifierHQ/unifier-guilded to install Guilded Support.
Misconfiguration, such as a missing Guilded bot token, will result in the upgrade failing. This is caused by the System Manager being unable to start Revolt Support, and in most cases can be fixed by running u!load bridge_guilded. If this does not help, run u!restart.
If all goes well, Guilded Support will be running and your Guilded bot will be up and running. You can always stop Guilded Support by running u!stop-guilded.
Alternatively, you can also run u!unload bridge_guilded to stop Guilded Support.
If you wish to stop Guilded Support from loading on boot, please uninstall the Plugin. All dependencies and configuration files will be retained.
Upgrading Unifier
To upgrade Unifier, you can use the System Extension/Upgrader to update the bot to the latest version. Run u!upgrade to check for upgrades, then upgrade if one is available. You can also run u!upgrade system force to upgrade to the newest files in the Unifier repo, regardless of whether a new upgrade is available or not.
Assigning moderators
To help keep your chat clean, Unifier lets you add moderators that can delete messages and temporarily or permanently ban users from Unified Chat. Admins can assign them by running u!addmod @user, or unassign them by running u!removemod @user. The changes will be reflected in data.json automatically.
Making a room
Unified Chat depends on "rooms". If you send something in a channel linked to the main room, they will be sent to all other channels linked to the same room.
Rooms can be created by admins only. To create a room, run u!make <room>. You can add rules using u!addrule <room> <rule>, lock authors to admins only using u!roomlock <room>, and restrict people who can connect to your room to admins only by using u!roomrestrict <room>.
Next steps
Congratulations, your Unifier instance is ready to go! Follow the Getting started for the official instance to connect your servers.
Here's some further guides you can follow to make the best out of Unifier:
ModerationGlobal emojisUpgrading UnifierTroubleshooting
Bot crash: "no module named ulid/typing-extensions/aenum"
Python's pip, for some reason, may not have installed revolt.py's dependencies correctly. To solve this, you can manually install the three extensions.
If you're using Pterodactyl panel to manage your Unifier server, add ulid typing-extensions aenum to "Additional Python packages". This will ensure that the missing libraries are installed on boot.
Cannot install Revolt/Guilded Support: repository URL or plugin.json file is invalid
Please check that the URL exactly matches what we've provided. If it does match, please make sure if you have git installed on your system.
If the issue persists after installing Git, please restart Unifier. If the issue persists even after restart, or Git was already installed when you got the error, please open a GitHub issue on the repository.
Unifier is not reaching its advertised speeds
Unifier's bridge speed will vary depending on various factors such as but not limited to your server specifications, server region, and Discord API performance. Most of the time, though, Unifier should be able to reach around 20-25MPS outside the US, and possibly 30+MPS within the US.
We were able to achieve 20MPS consistently, peaking at 26MPS, with our main VPS that we use to host the official Unifier instance:
Type: VPS
Provider: Akamai Connected Cloud (formerly Linode)
Location: Frankfurt, Germany
CPU: Shared 2-core AMD EPYC 7713
RAM: 4 GB
Network in/out: 40 Gbps/4 Gbps
We got these speeds in real-world conditions, so others should be able to too.
Last updated