TFMC-Discord/README.md

Discord-Minecraft Bridge with Shulker

A Dockerized Discord-Minecraft chat bridge using Shulker. This allows bidirectional communication between your Minecraft server and a Discord channel - players can chat from Discord to Minecraft and vice versa.

Features

• Bidirectional Chat: Messages from Minecraft appear in Discord, and Discord messages are sent to Minecraft
• Docker-based: Easy deployment with Docker Compose
• Flexible Configuration: Support for both Discord bot and webhook modes
• Log Tailing: Automatically reads Minecraft server logs without needing additional plugins
• RCON Support: Optional RCON integration for sending Discord messages to Minecraft

Prerequisites

• Docker and Docker Compose installed
• A Discord bot token (see Creating a Discord Bot)
• A Minecraft server with accessible log files
• (Optional) RCON enabled on your Minecraft server for full bidirectional chat

Quick Start

1. Clone and Initialize

git clone <your-repo-url>
cd TFMC-Discord
git submodule update --init --recursive

2. Configure Environment

Edit docker-compose.yml and update the environment variables:

environment:
  DISCORD_TOKEN: "YOUR_DISCORD_BOT_TOKEN_HERE"
  DISCORD_CHANNEL_ID: "YOUR_DISCORD_CHANNEL_ID_HERE"
  WEBHOOK_URL: ""  # Optional: Use webhook instead of bot
  SERVER_NAME: "My Minecraft Server"
  # ... other settings

Important: Update the volume path to point to your Minecraft server's log directory:

volumes:
  - /path/to/your/minecraft/logs:/minecraft/logs:ro

3. Run

docker compose up -d --build

The container will:

1. Build the Shulker application from the submodule
2. Generate a config.json from the environment variables
3. Start tailing your Minecraft server logs
4. Bridge messages between Discord and Minecraft

Configuration

Environment Variables

Variable	Required	Description	Default
DISCORD_TOKEN	Yes*	Discord bot token	-
DISCORD_CHANNEL_ID	Yes*	Discord channel ID for chat	-
WEBHOOK_URL	No	Discord webhook URL (alternative to bot)	-
SERVER_NAME	No	Server name shown in Discord	"Minecraft Server"
SERVER_IMAGE	No	Server avatar URL in webhook mode	""
DISCORD_MESSAGE_TEMPLATE	No	Message format template	"<%username%> %message%"
DEBUG	No	Enable debug logging	"false"
IS_LOCAL_FILE	No	Use log file tailing	"true"
LOCAL_FILE_PATH_OVERRIDE	No	Custom log file path	"/minecraft/logs/latest.log"

* Either DISCORD_TOKEN + DISCORD_CHANNEL_ID OR WEBHOOK_URL is required

Bot vs Webhook Mode

Bot Mode (recommended):

• Requires a Discord bot token and channel ID
• Better for interactive features
• Can use RCON to send messages to Minecraft

Webhook Mode:

• Only requires a webhook URL
• One-way: Minecraft → Discord
• Simpler setup but limited functionality

RCON Configuration

To enable Discord → Minecraft messages, you need RCON enabled on your Minecraft server.

1. Enable RCON in your server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_secure_password

2. Add RCON settings to your environment or edit /data/config.json after first run:

{
  "MINECRAFT_SERVER_RCON_IP": "your-minecraft-server-ip",
  "MINECRAFT_SERVER_RCON_PORT": 25575,
  "MINECRAFT_SERVER_RCON_PASSWORD": "your_secure_password"
}

Creating a Discord Bot

1. Go to the Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to the "Bot" tab and click "Add Bot"
4. Under "Token", click "Copy" to get your DISCORD_TOKEN
5. Enable "Message Content Intent" under "Privileged Gateway Intents"
6. Go to "OAuth2" → "URL Generator"
   • Select scopes: bot
   • Select permissions: Send Messages, Read Messages/View Channels, Read Message History
7. Copy the generated URL and open it in your browser to invite the bot to your server
8. Right-click on the channel where you want the chat bridge and click "Copy Channel ID" to get your DISCORD_CHANNEL_ID
   • You may need to enable Developer Mode in Discord Settings → Advanced → Developer Mode

Volumes

• /data - Stores config.json (mounted as tmpfs by default since config is generated from env vars)
• /minecraft/logs - Mount your Minecraft server's log directory here (read-only)

Updating Shulker

Shulker is included as a Git submodule. To update to the latest version:

git submodule update --remote external/shulker
docker compose build shulker
docker compose up -d shulker

Troubleshooting

Messages not appearing in Discord

• Check that your DISCORD_TOKEN and DISCORD_CHANNEL_ID are correct
• Ensure the bot has permissions to send messages in the channel
• Check logs: docker compose logs shulker

Messages not appearing in Minecraft

• Verify RCON is enabled and configured correctly in server.properties
• Check RCON credentials in config.json
• Ensure the Minecraft server is accessible from the Docker container
• Test RCON connectivity separately

Log file not found

• Verify the volume path points to the correct directory
• Ensure latest.log exists in the mounted directory
• Check file permissions (should be readable by container user)

Modded Server Issues

If you're running a modded server (Forge, Fabric, etc.), you may need to adjust the REGEX_SERVER_PREFIX setting. See Shulker's FAQ for details.

Advanced Configuration

After the first run, you can manually edit /data/config.json for advanced settings. Stop the container, edit the file, and restart:

docker compose down
# Edit config.json in the Docker volume
docker compose up -d

For all available configuration options, see the Shulker documentation.

Technical Details

• Built on Node.js 22 Alpine
• Runs as non-root user (uid 10001)
• Uses IS_LOCAL_FILE mode for log tailing (no webhook server needed)
• Configuration is generated from environment variables via the entrypoint script
• The Shulker source code is maintained as a Git submodule and built during Docker image creation

License

This project uses Shulker which is licensed under MIT. Please see the Shulker repository for its license terms.

Shulker Discord-Minecraft Bridge (Dockerized)

This repo includes Shulker as a Git submodule under external/shulker, plus a Docker setup so you can run it and mount your Minecraft logs as a volume.

Prereqs

• Docker and Docker Compose installed
• A Discord bot token and (optionally) a Discord channel webhook
• Your Minecraft server configured with rcon and accessible logs

First-time setup

1. Initialize and update submodules:
   • git submodule update --init --recursive
2. Configure environment variables (create a .env in repo root or pass via CLI):
   • DISCORD_TOKEN=... (required)
   • DISCORD_CHANNEL_ID=... (required if not using webhooks only)
   • WEBHOOK_URL=... (if using webhooks)
   • MC_LOGS_DIR=/absolute/path/to/your/minecraft/logs (defaults to ./Worlds/tfmc23-24/logs)
   • IS_LOCAL_FILE=true to tail logs directly (recommended when logs are mounted)

Run

Start the service (from repo root):

docker compose up -d --build shulker

On first run, /data/config.json will be created from config.example.json. The container will symlink it to /app/config.json and set IS_LOCAL_FILE and LOCAL_FILE_PATH to /minecraft/logs/latest.log by default. You can edit config.json by entering the container or by stopping the container and editing the file in the named volume.

Expose the Shulker webhook on port 8000 if you want to send remote hooks instead of tailing logs. For remote setup, set IS_LOCAL_FILE=false and follow the command in Shulker's README to pipe log lines to the webhook.

Volumes

• shulker_data named volume stores config.json.
• ${MC_LOGS_DIR} (host) is mounted read-only at /minecraft/logs (container). Ensure this path contains latest.log.

Updating Shulker

Shulker is a submodule:

git submodule update --remote external/shulker

Rebuild the image after updating:

docker compose build shulker && docker compose up -d shulker

Notes

• Node 16+ is required; the Docker image uses Node 18 Alpine.
• If your server is modded, you may need to adjust REGEX_SERVER_PREFIX per Shulker’s FAQ.
• For RCON features, set MINECRAFT_SERVER_RCON_* in config.json and ensure your server has rcon enabled.