|
| 1 | +--- |
| 2 | +title: Super-Spork |
| 3 | +description: this is a readme file for my project "super-spork" on github |
| 4 | +date: 2025-08-01 |
| 5 | +draft: false |
| 6 | +toc: true |
| 7 | +ShowLastmod: true |
| 8 | +--- |
| 9 | + |
| 10 | +https://github.com/demetrebadzaradze/super-spork |
| 11 | +## Super-Spork |
| 12 | +This project provides a bot that forwards text messages from Mumble server running in the docker with compose (version 1.5.735) to a Discord server. it is not a plug and play like just adding the bot to Discord and be done. it is more of making your own discord bot and running this project as docker to use the bot as a one way bridge for now. |
| 13 | + |
| 14 | +this is very bare bone project as you can tell and will improve lattes if gets any users. |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +## Features |
| 19 | + |
| 20 | +- Mumble-to-Discord: Forwards messages from Mumble channels to a Discord channel, including the sender's name and channel name (e.g., **TG_3W3p** in **Minecraft**: Hello from Mumble!). |
| 21 | + |
| 22 | +- Basic Discord Commands: Responds to simple commands like ?hello or hi with responses like `yooooo` or `whats` up (via the responce.py cog), and can gamble too. |
| 23 | + |
| 24 | +## Prerequisites |
| 25 | +- System: Ubuntu 24.04.1 LTS (or compatible Linux distribution), but since it runs in the docker you could make it work anywhere. |
| 26 | +- Docker: Docker and Docker Compose installed (`sudo apt install docker.io docker-compose`). |
| 27 | +- Mumble Server: Version 1.5.735 running in a Docker container. |
| 28 | +- Python: Version 3.12 (included in the bot's Docker image). |
| 29 | +- Dependencies: Listed in requirements.txt (e.g., `discord.py`, `zeroc-ice` for Ice communication). |
| 30 | +- Discord Bot Token: create your own discord bot and Obtain its token from the Discord Developer Portal. |
| 31 | +- Mumble Ice Password: this should be same as `MUMBLE_CONFIG_SERVERPASSWORD` from mumble server. |
| 32 | +- Discord Channel ID: The ID of the Discord channel where Mumble messages are forwarded (e.g., `1349705376263418589`). |
| 33 | + |
| 34 | +## Setup Instructions |
| 35 | + |
| 36 | +Directory Structure should look like this |
| 37 | +``` plain |
| 38 | +├── .env (same file as in super-spork) |
| 39 | +├── docker-compose.yml |
| 40 | +├── data/ |
| 41 | +├── logs/ |
| 42 | +└── super-spork/ |
| 43 | + ├── .env |
| 44 | + ├── cogs/ |
| 45 | + │ ├── mumble.py |
| 46 | + │ ├── responce.py |
| 47 | + ├── Dockerfile |
| 48 | + ├── MumbleServer_ice.py |
| 49 | + ├── main.py |
| 50 | + └── requirements.txt |
| 51 | +``` |
| 52 | +for that: |
| 53 | +1. clone the `super-spork` directory where mumble server compose file is. go to the correct directory(e.g. `cd /mnt/silver-64/opt/mumble/`) and clone the repo |
| 54 | +```bash |
| 55 | + git clone https://github.com/demetrebadzaradze/super-spork.git |
| 56 | +``` |
| 57 | + |
| 58 | +2. **make a discord bot** |
| 59 | + 1. go to [discord developer portal](https://discord.com/developers/applications) |
| 60 | + 2. create new application and give it a name |
| 61 | + 3. configure it as you would like in general (e.g. add a picture, description, etc.) |
| 62 | + 4. go over in the `bot` section and note the bot token (reset if not present) |
| 63 | + 5. then add the bot to the server with a [generated link,](https://discordjs.guide/preparations/adding-your-bot-to-servers.html#creating-and-using-your-invite-link) for permeations it should work with: |
| 64 | + `View Channels`, `Send Messages` , `Manage Messages`, `Read Message History`. |
| 65 | + I checked `admin` witch is not recommended but it works if you cant get it working other way. and also you can send this link to owner of another server and they could add it to server that you don't own. |
| 66 | + |
| 67 | +3. **Configure the Mumble Server** |
| 68 | +Ensure the Mumble server is running in a Docker container with Ice enabled: |
| 69 | +**template `compose.yml` file for `mumbe` server and `super-spork` bot ** |
| 70 | +```yml |
| 71 | +services: |
| 72 | + mumble-server: |
| 73 | + image: mumblevoip/mumble-server:latest |
| 74 | + container_name: mumble-server |
| 75 | + hostname: <replace this with your hostname> |
| 76 | + restart: on-failure |
| 77 | + ports: |
| 78 | + - 64738:64738 |
| 79 | + - 64738:64738/udp |
| 80 | + - 6502:6502 |
| 81 | + volumes: |
| 82 | + - ./data/:/data |
| 83 | + environment: |
| 84 | + MUMBLE_CONFIG_WELCOMETEXT: <replace this with your welcome text> |
| 85 | + MUMBLE_CONFIG_PORT: 64738 |
| 86 | + MUMBLE_CONFIG_USERS: <replace this with max users for server> |
| 87 | + MUMBLE_CONFIG_ICE: "tcp -h 0.0.0.0 -p 6502" |
| 88 | + MUMBLE_CONFIG_SERVERPASSWORD: <replace this with your server password witch will be also needed in .env file> |
| 89 | + MUMBLE_SUPERUSER_PASSWORD: <replace this with your SuperUser password> |
| 90 | + expose: |
| 91 | + - 6502 |
| 92 | + networks: |
| 93 | + - mumble-network |
| 94 | + |
| 95 | + super-spork-bot: |
| 96 | + build: |
| 97 | + context: ./super-spork/. |
| 98 | + dockerfile: Dockerfile |
| 99 | + container_name: super-spork-bot |
| 100 | + restart: on-failure |
| 101 | + environment: |
| 102 | + - TOKEN=${TOKEN} |
| 103 | + - DISCORD_CHANNEL_ID=${DISCORD_CHANNEL_ID} |
| 104 | + - MUMBLE_ICE_PASSWORD=${MUMBLE_ICE_PASSWORD} |
| 105 | + volumes: |
| 106 | + - ./super-spork:/app |
| 107 | + - ./logs:/app/logs |
| 108 | + depends_on: |
| 109 | + - mumble-server |
| 110 | + networks: |
| 111 | + - mumble-network |
| 112 | +networks: |
| 113 | + mumble-network: |
| 114 | + driver: bridge |
| 115 | +``` |
| 116 | + |
| 117 | + |
| 118 | + 4. **configure `.env` file** |
| 119 | + this env file should be in the `super-spork` directory and where `compose.yml` file is and this is how it should look like: (replace descriptions in quotes with actual values) |
| 120 | +```env |
| 121 | + TOKEN="this should be set to your discord bot's token" |
| 122 | + DISCORD_CHANNEL_ID="id of a channel where messages will be sent bot should be added in that server too" |
| 123 | + MUMBLE_ICE_PASSWORD="whatever is configured as MUMBLE_CONFIG_SERVERPASSWORD in mumble configuration" |
| 124 | +``` |
| 125 | + |
| 126 | +5. **Build and run the container** |
| 127 | + go to directory where `compose.yml` file is and run: |
| 128 | + ```bash |
| 129 | + sudo docker compose up --build |
| 130 | + ``` |
| 131 | + use `-d` for detached mode. |
| 132 | +6. **Test** |
| 133 | +when any message is sent in the `mumble` text chat it will also be send in the `discord` channel like this : |
| 134 | +```markdown |
| 135 | +**TG_3W3p** in **Minecraft**: hello world |
| 136 | +``` |
| 137 | + |
| 138 | +## Contributing |
| 139 | + |
| 140 | +- Add new features by creating cogs in super-spork/cogs/ and updating main.py. |
| 141 | +- Report issues or suggest improvements by modifying the code. |
| 142 | + |
| 143 | +## License |
| 144 | + |
| 145 | +This project is licensed under the MIT License. See the LICENSE file for details. |
0 commit comments