Unifier
Install guide for Unifier v3.0.0 and newer.
Used the (Legacy) 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:
Optimized and Balanced installations require Python 3.12 or above.
Stable requires Python 3.9 or above.
Recommended system requirements
We recommend the following for Unifier:
64-bit CPU based on x86_64 or arm64/aarch64 that can run Python 3.12 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.
We have plans to provide a Docker image in the near future.
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, we recommend using the Balanced option, as it includes additional libraries for performance optimization and the latest tested version of Nextcord. If you want the absolute best experience from Unifier, you should use the Optimized option, which is similar to Balanced but includes the very latest version of Nextcord. However, if these options cause issues, or you want maximum stability, you should choose Stable which only includes the essentials.
To choose an installation option, type its corresponding option number, then press enter. After you have chosen the installation option, you will be able to choose the Python environment you want to use, if your host system uses Linux or macOS.
The default environment will be marked with a star. Although you can choose any of the supported versions, we recommend using the latest version possible (this will be at the top of the list) for best performance. You will also be asked if you want to create a virtual environment for the selected Python environment, or if you want to use the existing environment if it exists in the install directory.
Once you've selected your environment (or if you're on Windows), you should see the confirmation dialog.
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!system reload <extension>: Reloads an extension, useful for updating extensions without restarting the entire bot.u!system eval <command>: Evaluates a Python command. Only use if you know what you're doing!u!system install <plugin>Installs a plugin from a Git repository. A valid plugin.json file is required.u!system uninstall <plugin>: Uninstalls a plugin.u!system upgrade [plugin] [args]: Upgrades a plugin. If all arguments are left empty, it will upgrade Unifier.u!system shutdown: Shuts the bot down.u!system reboot: Reboots the bot.
Further setup
Installing Revolt Support
First, you will need to create a Revolt bot, then add its token to the tokens list. To do this, shut down the bot (if it's already running), then run:
sh run.sh --tokenson Linux/macOS, or./run.bat --tokenson Windows
to open the token manager. Enter your token encryption password, then type add-token, then add a token under the TOKEN_REVOLT key.
You will also need to add user IDs of admins as admin_ids, as well as the user ID of the bot's owner. As Unifier's admins list allow both integers and strings, you can have both Discord and Revolt users under the same list. Your config.toml file should now look something like this:
After starting the bot, you can run u!system 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!system load bridge_revolt. If this does not help, run u!system 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.
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
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 tokens list. To do this, shut down the bot (if it's already running), then run:
sh run.sh --tokenson Linux/macOS, or./run.bat --tokenson Windows
to open the token manager. Enter your token encryption password, then type add-token, then add a token under the TOKEN_GUILDED key.
You will also need to add user IDs of admins as admin_ids, as well as the user ID of the bot's owner. As Unifier's admins list allow both integers and strings, you can have both Discord and Guilded users under the same list. Your config.toml file should now look something like this:
After starting the bot, you can run u!system 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!system load bridge_guilded. If this does not help, run u!system 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.
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!system upgrade to check for upgrades, then upgrade if one is available. You can also run u!system 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!config addmod @user, or unassign them by running u!config removemod @user. The changes will be reflected in data.json automatically.
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:
Troubleshooting
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 correct repository.
Winloop failed to build
If winloop fails to build for whatever reason, you should use the Stable installation. This won't limit any features, but it will probably be slower than Optimized and Balanced installations.
Unifier is not reaching its advertised speeds
When Unifier starts up, it will have no Webhooks in its Webhook cache. This means that for each server, Unifier will need to fetch the bridge Webhooks from Discord's API, which adds additional latency. However, once you send your first message, Unifier will cache as many Webhooks as it can, so that subsequent messages can be bridged even faster.
Also, consider using the Optimized installation. It includes a lot of extra libraries to speed things up.
Unifier is still 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