Unifier (older versions)
Install guide for Unifier v2 and older.
This guide is for Unifier v2 and older. If you're installing a newer version of Unifier, consult the modern guide instead.
Used the Installer?
You can skip right to Running Unifier!
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 v1.2 and v2 can be installed on Python 3.13.0rc2 and newer but have the following caveats:
Nextcord in some cases cannot be installed using user installation. In this case, it must either be installed on a virtualenv or globally.
RaidGuard plugin cannot be installed as jellyfish is not compatible with Python 3.13 yet.
Please note that this is for advisory purposes only and we will remove this note as soon as we learn the above issues have been patched.
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
Recommended system requirements
We recommend the following for Unifier:
64-bit CPU based on x86_64 or ARM64 that can run Python 3.11 or newer
20 Mbps or faster internet connection
Python 3.11 or newer
Dependencies
As there's a lot of requirements now, we've decided not to list them here. A requirements.txt should have been provided to you, so please consult that instead. To install the dependencies, please open your terminal, change the working directory to Unifier's root folder, then run:
MacOS/Linux:
python3 -m pip install requirements.txtWindows:
py -3 -m pip install requirements.txt
If you're installing Unifier v1.2/v2 on Windows: This will fail. Please remove uvloop from the requirements.txt file and retry.
If you're installing Unifier v3+ on Windows: This should work, because pip will install winloop instead of uvloop. Please let us know if you encounter windows.
If you're using Pterodactyl panel, this should be done for you once you start the bot.
Installation
Other than dependencies, Unifier requires no installation process. It is ready to be run out-of-the-box, with no compilation needed.
We do not provide Docker containers or anything similar. By "out-of-the-box", we mean that its source code can be ran in whatever system with very little to no extra steps.
Configuration
A base config.json file should have been provided to you. This configuration is near identical to our config.json file on the official instance, so it can serve as a good template.
Set bot token
To log in to Discord, Unifier needs to connect to a bot account. By giving it a token, it gives Unifier a "password" to log in to that account.
WARNING: Do NOT share this token to anyone you don't trust, not even us!
As of Unifier and Unifier Micro v1.1.8, tokens in config files are no longer supported. You will have to use .env files.
Create a .env (dotenv) file, then add your token as the value for the TOKEN key. Your .env file should look like this:
This file should be EXACTLY named .env, not .env.txt, .env.json, just .env, nothing more.
Assigning Unifier admins
You can assign admins by adding their user IDs in the admin_ids list in config.json. By assigning admins, you grant them the ability to manage rooms and moderators.
You can use integers for Discord user IDs and strings for Revolt/Guilded user IDs.
Admins do not have access to admin.py commands, only certain config.py commands.
Configuring logging & reporting
Unifier logs all deleted messages in its room channels, as well as provides a central space for all message reports. Please ensure your moderators (who you can assign in the next section) have access to these channels, as they are essential for proper moderation.
To configure logging and reporting, open bridge.py, then add the logging server's ID, logging channel's ID, and reports channel's ID in the appropriate variables. The variables have been named in a way so it's obvious what they are for.
Configuring update channels
You will need to add a versioning repository and source code repository, so Unifier can check for upgrades. If the former repository has an update.json file with a higher release value than the update.json file stored in Unifier's root directory, Unifier can know that an update is available.
So, you will need two repositories:
unifier, for the source code, andunifier-version, for versioning.
Unifier does not support custom repository names for updates yet!
unifier-version is available to the public, so if your Unifier instance will follow upgrades from the official repositories, you can use this as your versioning repo.
Once you have the repositories ready, set check_endpoint as your versioning repository (e.g. https://github.com/UnifierHQ/unifier-version.git), and files_endpoint as the URL to the user that owns the unifier repository you will use. So this should be something like https://github.com/UnifierHQ, or if you're using a Personal Access Token, then it should be something along the lines of https://github_pat_acc355t0k3ng035h3r3@github.com/UnifierHQ.
The .git at the end of the version endpoint is MANDATORY. Version checking will not work without it.
Running Unifier
You can run Unifier on whatever system that supports Python 3.8 or newer and Unifier's dependencies. If you're self-hosting and running Unifier through the shell (bash, zsh, etc), we recommend you use the screen package (this is NOT a Python library) so you can keep it running in the background, even after closing the shell.
Windows users may not be able to use screen. Please find an alternative way to run Unifier in the background, or use a server.
But before you run the bot, we recommend you add it to your home server (where the logging channels are located in). You can do this by copying your bot's client ID, then going to https://discord.com/api/oauth2/authorize?client_id=<client_id>&permissions=537259008&scope=bot. Remember to replace <client_id> with the bot's client ID!
Self-hosted
First, open a screen instance by running screen -S unifier. This will open an empty shell. Then, change the screen's directory to wherever Unifier is located by running cd ./path/to/dir, with ./path/to/dir being the path of wherever you installed Unifier. If Unifier is located in a folder called unifier which is conveniently in the same folder that your shell is in, then you can run cd ./unifier.
Once you have done that, run python3 unifier.py to run Unifier. If it's running properly, then congratulations!
You can manage the screen by running screen -Dr unifier.
Do not Ctrl+C the unifier screen with Guilded Support installed, otherwise the bot may hang on shutdown. We highly recommend using the graceful shutdown command (u!shutdown) instead, so message cache is preserved for next boot.
If you must forcibly shut Unifier down, run screen -X -S unifier quit to force quit whatever is running in the screen, as well as close the screen entirely. You cannot run screen -Dr unifier after this, and you will need to run screen -S unifier to create a new screen.
Managed
This is a guide for the Pterodactyl panel, as many free hosting services use this panel. If your hosting service uses a different panel, please contact them for assistance.
Additionally, this part of the guide assumes you have created a server already. If you haven't, please create a Python server.
As Unifier already has a requirements.txt file, you do not need to modify anything else except the App PY file and Python version. These options can be found in the Startup page.
Some hosts may not allow conflicting dependencies by default, however Unifier will run even with conflicts. This is likely due to the aiohttp requirement causing conflicts, as we made it be a later version due to a security vulnerability with an older version of the package.
To fix this, you can either:
Modify requirements.txt to not have the aiohttp requirement, or
Delete requirements.txt, then add the modules to "Additional packages". This should be a copy-paste from the requirements.txt file, and should look like
--no-dependencies novus>=0.2.4 guilded.py revolt.py>=0.2.0 ...
Change the App PY file value to unifier.py, and the Python version to Python 3.8 or later. We recommend using Python 3.11.
Once you have done that, you can return to the Console, then press Start to start Unifier. If it's running properly, then congratulations!
Using System Manager (v1.2.0+)/admin.py (v1.1.x)
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 and admin.py whatsoever for this very reason.
Unifier has a powerful System Manager on v1.2.0 and newer or an admin extension to effortlessly run commands and manage extensions. It's like the package manager (like apt and pacman) of Unifier. However, admin.py does not have any functionality to automatically load extensions on startup, so you will need to modify unifier.py to load them on startup instead. On Unifier v1.2.0+, System Manager handles extension loading, so if you install a plugin it'll always be loaded on startup.
To use admin commands, you first need to set the owner ID to yours. Otherwise, it will not grant you access to its commands.
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>(v1.2.0+): Installs a plugin from a Git repository. A valid plugin.json file is required.
Further setup
Installing Upgrader
Upgrader has been discontinued. This guide will be removed on July 5th
Since you have the update channels set up, you can run u!install-upgrader to install the Upgrader to your Unifier installation. Having the Upgrader will let you be able to easily upgrade Unifier to the latest version when a new upgrade is available.
Follow the instructions from the bot to install Upgrader once you've run the command.
Installing Revolt Support
You will need Python 3.9 or above to install 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 the following command to install Revolt Support:
v1.2.0 and newer:
u!install https://github.com/UnifierHQ/unifier-revoltv1.1.x and older:
u!install-revolt
Misconfiguration, such as a missing Revolt bot token, will result in the upgrade failing. This is caused by the System Manager/Upgrader being unable to start Revolt Support, and can be fixed by running u!load bridge_revolt on v1.2.0+ or u!start-revolt on v1.1.x and older.
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.
In Unifier v1.2.0 and newer, you can also run u!unload bridge_revolt to stop Revolt Support. However, this will not work on Unifier v1.1.x and older.
If you wish to stop Revolt Support from loading on boot, please remove revolt from externals.
Installing Guilded Support
Guilded Support is experimental. Expect things to break and not work at times.
We highly recommend you install Guilded Support on a secondary instance until stable release.
"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 the following command to install Revolt Support:
v1.2.0 and newer:
u!install https://github.com/UnifierHQ/unifier-guildedv1.1.x and older:
u!install-guilded
Misconfiguration, such as a missing Guilded bot token, will result in the upgrade failing. This is caused by the System Manager/Upgrader being unable to start Guilded Support, and can be fixed by running u!load bridge_guilded on v1.2.0+ or u!start-guilded on v1.1.x and older.
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.
In Unifier v1.2.0 and newer, you can also run u!unload bridge_guilded to stop Guilded Support. However, this will not work on Unifier v1.1.x and older.
If you wish to stop Guilded Support from loading on boot, please remove guilded from externals.
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 on v1.2.0+ or u!upgrade force on v1.1.x or older to upgrade to the newest files in the Unifier repo, regardless of whether a new upgrade is available or not.
On v1.2.0+, System Manager manages the upgrades and will be upgraded when system plugins are upgraded.
On v1.1.x or older, you can use u!upgrade-upgrader to upgrade the Upgrader to the latest version. Upgrader will refuse to upgrade Unifier unless it is up to date.
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