TFMC-Discord/README.md

# Discord-Minecraft Bridge with Shulker

A Dockerized Discord-Minecraft chat bridge using [Shulker](https://github.com/destruc7i0n/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](#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

```bash
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:

```yaml
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:

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

### 3. Run

```bash
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`:
```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:
```json
{
  "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](https://discord.com/developers/applications)
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:

```bash
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](https://github.com/destruc7i0n/shulker#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:

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

For all available configuration options, see the [Shulker documentation](https://github.com/destruc7i0n/shulker).

## 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](https://github.com/destruc7i0n/shulker) which is licensed under MIT. Please see the Shulker repository for its license terms.
 

## Shulker Discord-Minecraft Bridge (Dockerized)

This repo includes [Shulker](https://github.com/destruc7i0n/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.