Skip to content

Latest commit

 

History

History
89 lines (73 loc) · 6.57 KB

INSTALLATION.md

File metadata and controls

89 lines (73 loc) · 6.57 KB
Raw

Installing Emote Collector

I can think of two reasons you'd want to install this bot:

  1. You have to test some changes you made.
  2. You want to run a copy of the bot for yourself.

If you do 2), please rename the bot and change the icon. Also, please do not run this bot for public use. I implore you to enable the "private bot" option in the developer panel.

Prerequisites

  • libmagickwand-dev, for emote resizing via the Wand library
  • PostgreSQL 10+, for persistent data storage
    • Postgres database administration ability (backup, migration, role management etc)
  • At least 2 GB of RAM (image resizing is memory hungry)
  • Python 3.6+
  • Two bot tokens (one for the bot itself, and one for the backend_creator script to create guilds)
  • One additional user account per 100 backend servers needed
  • All requirements specified in the setup.py file.

How Emote Collector works

To get an overview, it is important to first understand how the bot works. There are several components to this bot. In rough order of importance:

  • The backend servers, which are created by the backend_creator script. These are used to store user-generated emotes.
  • The backend_creator script itself, which creates backend servers owned by separate user accounts, one per 100 backend servers, since user accounts may only be in 100 servers maximum.
    • A server is deemed a backend server if it is owned by any of the configured backend user accounts.
    • Emote Collector needs administrator access in all of these servers to create emotes, delete messages, and re-create channels (see "gimme system" below). This permission is granted by the backend_creator script.
      • Administrator is not strictly needed, however, since the servers are only used by Emote Collector anyway and their entire purpose is to store emotes, there is no risk in granting administrator.
  • The cache synchronization system, which is used to allow the Emote Collector website and API to access the list of emote moderators (who are authorized to modify other users' emotes) which is determined by a configured role in an optional configured support server, and the list of backend servers. to choose from.
    • The core functionality of the bot thus works without access to a websocket, which is important for scalability of the web server since it imports and uses emote collector's code.
  • The emote decay system, which removes old and unused emotes to make room for new ones, if configured.
  • Emote logging, for transparency, data recovery, and moderation purposes.
  • The "gimme" system which allows users to be invited to backend servers. Emote Collector deletes all messages sent in the backend servers after 5 seconds, in order to prevent me being liable for moderating hundreds of servers. In case any messages were missed, on startup, Emote Collector erases and recreates all channels in the backend servers and creates a new one in order to invite people to them.

There are more components, but these are the ones you should know about.

Adding an emote

When a user adds a new emote:

  1. The image is fetched from the internet.
  2. The image is validated as a GIF, PNG, or JPEG file.
  3. If the image is too big to be uploaded to discord (>256 KiB) it is repeatedly resized in 1/2 increments until it does fit using Wand. This is done in a subprocess to reduce memory leaks, as when a process is killed all of its memory is reclaimed by the system.
  4. If the image is not too big after that, a backend server is picked which has enough static or animated slots for the emote, depending on the type of the image
    • The backend server picked is the one that least recently had an emote added to it. This is to minimize being rate limited, as the emote rate limits are very strict.
  5. The emote is uploaded to the chosen backend server.
  6. The emote data that Discord gives us is then inserted into the database, along with our own data (the user who created the emote).
  7. The emote creation is logged to all configured discord channels, if applicable.

Installation

git clone https://github.com/EmoteCollector/EmoteCollector.git ec
cd ec
python3 -m venv .venv
source .venv/bin/activate
pip install -U setuptools pip wheel
pip install -e .
  1. Run these sql commands in sudo -u postgres psql:
-- for ease of use, you can name the role you use after your system user account to use peer authentication
-- then you won't have to specify a username or password in the config file.
CREATE DATABASE ec WITH OWNER my_postgres_role;  -- or whatever you want to call the database
\c ec
CREATE EXTENSION pg_trgm;  -- used for searching for emotes by name
  1. psql ec -f emote_collector/sql/schema.sql
  2. Copy emote_collector/data/config.example.py to emote_collector/data/config.py, and edit accordingly. Make sure you touch the database and tokens, and backend_user_accounts sections.
  3. Create a brand new Discord user account. This is to hold the servers that will store the emotes. Unfortunately, every time I make a new alt, discord requires me to verify it by phone. If this happens to you, you must use an actual physical phone number, rather than a VoIP number, and it can't be used to verify another discord account within 24 hours.
  4. Create two bot applications under any Discord user account. One will be the backend server creation bot and one will be the public-facing Emote Collector bot. Preferably create these under your main account, rather than your backend account, so that your main has admin access to the bot (or use Teams).
  5. Run emote_collector/backend_creator.py <server creator bot token> <Emote Collector bot user ID> [existing backend server count]. Make sure you are signed in to the emote backend user account in your web browser. The optional last parameter is in case you need to stop the script and resume it later.
    • It'll create one server at a time, each time opening an invite link so that you can join the server. Then it will transfer ownership to you (your emote backend account) and open Emote Collector's invite link in your web browser.
    • After Emote Collector is invited to the server, the backend creator leaves the server so that it can make another one (bots are only allowed to create servers if they are in at most 10 servers total).
  6. Run python -m emote_collector.
  7. Optional: run an instance of the list website and set up its information in config.py.

Confused about how the backend creator works? Watch this video demo of it in action.

If you need any help, DM @lambda#0987 or file a GitHub issue.