- Music with player controls, DJ roles with vote skip, multi-node failover, smart autoplay, audio filters and much more!
- Auto-mod, mass moderation, tickets & detailed logging.
- Custom emojis synced from a simple
.zipupload. - Fully dockerized, deploys with a single
just upcommand.
| Tool | Version | Purpose |
|---|---|---|
| 20.10+ | To run the bot in a containerized environment. | |
| 2.50+ | To clone the repository and manage version control. | |
| 1.27+ | A command runner for the project's recipes. |
-
Clone the repository
git clone https://github.com/swayam25/Square-Bot square cd square -
Create
config.tomlfile from the providedconfig.example.tomland fill in the required values.cp config.example.toml config.toml
Tip
Check configuration section for details on the configuration keys.
-
Build the image and start the stack
just up
-
Done! The bot and its Postgres database are up.
just uprebuilds and redeploys.just downstops everything.
Note
The production stack is only the bot and its Postgres database. It has no web UI and exposes no ports. Logs go to stdout (docker compose -f docker-compose.prod.yml logs -f bot); any monitoring or database tooling is yours to add.
The bot needs at least one Lavalink node to play music. Nodes are configured as [[lavalink]] tables in config.toml, you can add more than one and the bot fails over to a healthy node if one dies.
flowchart LR
A["Player needs a node"] --> B{"Any [[lavalink]]<br/>node online?"}
B -- No --> C["Music commands fail"]
B -- Yes --> D["Use a healthy node"]
D --> E["Active node dies"]
E --> F["Fail over to the next<br/>healthy node"]
There's a community-maintained list of free public Lavalink nodes. Pick one and drop its host/port/password into a [[lavalink]] table.
Warning
Public nodes are shared with everyone else using that list. Expect rate limits, downtime, and credentials that rotate or die without notice.
Fine for a quick test, not something to rely on for production.
Running your own node gives you full control over performance, uptime, and audio sources. See the Lavalink docs for setup.
Note
Lavalink is a separate service, it isn't bundled in this repo's docker-compose files. Run it on its own (same host or elsewhere) and point a [[lavalink]] table at it.
Warning
It's best to host Lavalink on a different VPS than the one running the bot itself. Most big-name cloud providers (AWS, GCP, Azure, DigitalOcean, etc.) have their IP ranges rate-limited or blocked by YouTube, so playback breaks even though the node itself is perfectly healthy. A smaller, less popular host tends to dodge this.
| Key | Type | Description |
|---|---|---|
owner-id |
int |
The Discord ID of the bot owner. |
owner-guild-ids |
list[int] |
A list of Discord IDs of the owner's guilds. Owner/Developer only commands are created only in these guilds. |
system-channel-id |
int |
The Discord ID of the system channel where the bot will send startup, guild join/leave etc... messages. |
support-server-url |
str |
The invite URL of the support server. |
bot-token |
str |
Discord Bot Token. Get this from developer portal. |
database-url |
str |
The URL for the PostgreSQL database. |
colors.theme |
str |
The color theme for the bot's view containers. |
colors.green |
str |
The color code for green color in view containers. |
colors.red |
str |
The color code for red color in view containers. |
colors.orange |
str |
The color code for orange color in view containers. |
[[lavalink]] |
table |
A Lavalink node. Multiple [[lavalink]] tables can be configured, players fail over to another node if one dies. |
lavalink.host |
str |
The host of the Lavalink server. |
lavalink.port |
int |
The port of the Lavalink server. |
lavalink.password |
str |
The password for the Lavalink server. |
lavalink.secure |
bool |
Whether to use secure connection (wss) for Lavalink. |
The bot ships with a default set of Unicode emojis defined on the Emoji class in emoji.py. You can override any of these with your own Discord custom emojis.
How it works: every emoji is keyed by an attribute name on the Emoji class (e.g. success, error, loading). The bot loads overrides from .cache/emoji.json, matching each entry to an attribute by name. Any attribute without an override simply falls back to its default.
There are two ways to provide overrides - upload a .zip, or write .cache/emoji.json by hand.
The workflow is the same whether you use the emojis bundled with this bot or your own:
- Prepare a
.zipof.png/.gifemoji files. Each file name must match an attribute on theEmojiclass (e.g.success.png→ thesuccessattribute).To use the bot's built-in set, just grab the ready-made
emojis.zip. /emoji upload: Upload the.zipto register the emojis with Discord.
flowchart LR
A["Zip of .png/.gif files<br/>named after Emoji attributes"] --> B["/emoji upload"]
B --> C[".cache/emoji.json"]
C --> D["Emojis applied"]
If you already have the emojis, you can skip uploading and create .cache/emoji.json yourself:
{
"emoji_name": "<a:dc_emoji_name:dc_emoji_id>",
"emoji_name": "<:dc_emoji_name:dc_emoji_id>"
}| Field | Meaning |
|---|---|
emoji_name |
The attribute name on the Emoji class this override maps to. |
<a:...> / <:...> |
<a:...> is an animated emoji, <:...> is a static one. |
dc_emoji_name |
The emoji's name as it appears in Discord. |
dc_emoji_id |
The emoji's unique Discord ID. |
Contributions are welcome! See CONTRIBUTING.md for how to get a local copy running and what we look for in a pull request.
