Getting Started

Welcome to CraftDaemon! This documentation covers everything you need to know to install, configure, and run CraftDaemon on your Linux server. If this is your first time, read through each section in order, skipping steps is the most common cause of setup issues.

What is CraftDaemon?

CraftDaemon is a Discord bot that lets you manage your Minecraft server directly from Discord using slash commands. It integrates with systemd (Linux's service manager) to start, stop, and restart your server process, and uses RCON (a remote console protocol built into Minecraft) to query live server data like player count and TPS. You don't need to SSH into your server just to restart it, CraftDaemon handles it all from a Discord channel.

System Requirements

• Operating System: Linux with systemd (Ubuntu, Debian, Arch, etc.) - Check Operating System Compatibility
• Node.js: v18+ (v22 recommended; used for development and testing). To check what you have, run: node --version
• Minecraft Server:: Any server with RCON support enabled (Although Paper is recommended)
• Network: Outbound HTTPS access for the Discord API, and a local connection to RCON (127.0.0.1 by default)

Installation

Step 1: Clone the Repository

SSH into your Linux server and run the following to download CraftDaemon into the current directory, then navigate into it:

Step 2: Install Node.js Dependencies

This installs all required packages listed in package.json. Run this from inside the CraftDaemon directory:

If you get a "command not found" error, Node.js is not installed or not in your PATH. Verify with node --version and which node.

Step 3: Create Discord Bot Application

You'll need to create a bot account in Discord's developer portal. This gives you a token (like a password) that CraftDaemon uses to log in as your bot.

1. Go to Discord Developer Portal at discord.com/developers/applications
2. Click "New Application" and give it a name (e.g., "CraftDaemon")
3. Navigate to the "Bot" section in the left sidebar and click "Add Bot"
4. Click "Reset Token" to reveal your bot token, then copy it — you'll paste this into your .env file later. You only see it once, so save it now.
5. Scroll down to "Privileged Gateway Intents" and enable both:
   • Server Members Intent
   • Message Content Intent
6. Go to "OAuth2" → "URL Generator" in the left sidebar. Under "Scopes", check bot and applications.commands
7. Under "Bot Permissions", check: Send Messages, Embed Links, Read Message History
8. Copy the generated URL at the bottom of the page and open it in your browser to invite the bot to your Discord server

Step 4: Set Up Minecraft as a systemd Service (If you haven't already)

CraftDaemon controls your Minecraft server through systemd, Linux's service manager. If your server isn't already running as a systemd service, you'll need to set this up. Create the service file using a text editor with root privileges:

Paste the following content into the file, then save and exit (Ctrl+O, Enter, Ctrl+X in nano):

Adjust the following to match your setup before saving:

• User: the Linux user that owns the Minecraft server files
• WorkingDirectory: the full path to your server folder
• ExecStart: make sure the java path is correct (which java will tell you) and the .jar filename matches your actual server jar
• -Xmx8G / -Xms8G: the maximum and starting RAM for your server — adjust to suit your machine

Then reload systemd and enable the service to start on boot:

Step 5: Enable RCON on Your Server

RCON (Remote Console) is a protocol built into Minecraft that allows CraftDaemon to query live server data and send commands. You need to enable it in your server's server.properties file, which is located in your Minecraft server directory. Open it with:

Find and update (or add) these three lines:

Use a strong, unique password — this password must exactly match the RCON_PASSWORD value in your .env later. After saving, restart your Minecraft server:

Step 6: Configure Environment Variables

CraftDaemon uses a .env file to store all sensitive configuration like your bot token and RCON password. Start by copying the provided example file:

Then open it for editing:

Fill in your values. At minimum, set these required fields:

See the Configuration section for a full breakdown of every available variable.

Step 7: Register Slash Commands

Before users can see or use slash commands in Discord, they need to be registered with Discord's API. Run this once from the CraftDaemon directory:

Step 8: Set Up Sudoers Permissions

CraftDaemon needs to run systemctl commands (to start/stop/restart your Minecraft server) without being prompted for a password. This is done by adding a rule to the sudoers file. Always edit sudoers with visudo — it validates the file before saving and prevents you from locking yourself out:

Scroll to the bottom of the file and add this line, replacing botuser with the Linux username the bot runs as:

Save and exit (Ctrl+O, Enter, Ctrl+X). To verify which user the bot will run as, check your craftdaemon.service file's User= field.

Step 9: Install as systemd Service (Optional but Recommended)

Running CraftDaemon as a systemd service means it automatically starts on boot and restarts itself if it crashes. Create the service file:

Paste the following, then update User and WorkingDirectory to match your setup:

Make sure the node path in ExecStart is correct — run which node to find yours. Then enable and start:

Configuration

Environment Variables (.env)

All configuration is managed through config/.env. This file should never be shared or committed to Version Control, it lives only on your server (If you're using GitHub). If the file doesn't exist yet, create it by copying the example: cp config/.env.example config/.env, then edit it with nano config/.env. Here's a complete reference of every available variable:

Legend: ✅ = Required, ☑️ = Optional (defaults are used when omitted).

Permission Configuration

Edit config/permission-config.js to control which Discord roles and users can run which commands. Open it with nano config/permission-config.js. The file exports a single object with four keys:

• owner: an array of Discord user IDs that bypass all permission checks — typically just you
• roles: a map of short label names (e.g. ADMIN) to Discord role IDs
• commands: maps each permission key to an array of role labels that can use it
• users: optional per-user overrides that grant specific permission keys to individual users regardless of their roles

Replace the placeholder IDs with your actual Discord role and user IDs. Owners bypass all command checks entirely. Entries in users take precedence over role-based permissions — useful for granting or restricting access to specific individuals.

Commands Reference

/start

Starts the Minecraft server by running systemctl start on your configured service. The bot replies with a status embed confirming the start was triggered.

• Permission: server.start
• Response: Confirmation embed with server startup status
• Notes: The server itself may take 10–30 seconds to fully boot depending on world size — this is normal. The command only triggers the start; it does not wait for the server to be ready.

/stop

Gracefully stops the server. Before stopping, CraftDaemon sends a save-all command via RCON to ensure no world data is lost, then calls systemctl stop.

• Permission: server.stop
• Response: Confirmation embed with stop status
• Notes: This is safe to use at any time — the save-all happens automatically before shutdown

/restart

Restarts the server by saving world data first, then calling systemctl restart. Useful after config changes or to apply updates without manually stopping and starting.

• Permission: server.restart
• Response: Confirmation embed with restart status
• Notes: Like /stop, this always performs a save-all before restarting

/status

Shows a full live snapshot of your server: systemd service state, uptime, TPS (ticks per second), online player count, and current RCON round-trip latency.

• Permission: server.status
• Response: Rich embed with all server metrics
• Requires: A Paper server for full metrics (TPS, vanilla and other servers will not show TPS)
• Latency: Shows RCON round-trip time, which reflects the connection health between the bot and your server

/address

Displays your server's connection details: public IP/domain, LAN address, and the Java edition version label. Useful for sharing with players.

• Permission: server.address
• Response: Embed with connection details
• Requires: MAIN_ADDRESS and LOCAL_ADDRESS set in config/.env — the command still works without them but will show empty fields

/ping

Checks the bot's connection health by measuring Discord API round-trip latency. Does not interact with the Minecraft server.

• Permission: No restriction — all Discord members can use this
• Response: Simple message showing API latency in milliseconds
• Notes: Useful for confirming the bot is alive and responsive if other commands seem slow

/checkupdate

Fetches the latest release from GitHub and compares it to the version currently running. If a newer version is available, the full changelog is displayed in the embed.

• Permission: bot.checkUpdate
• Response: Embed showing current version vs latest GitHub release
• If newer: Displays the full changelog from the release notes

Permissions & RBAC

How Permissions Work

CraftDaemon uses a role-based access control (RBAC) system defined in config/permission-config.js. The idea is simple: each bot command has a permission key (e.g. server.start), and you decide which Discord roles can use it. You never configure permissions inside Discord itself — everything is in that one JS file on your server.

Available Permission Keys

Example Configuration

Here's a typical setup with Owner, Admin, and Moderator roles. Replace the placeholder IDs with your real ones (see "Finding Discord IDs" below):

Finding Discord IDs

Discord IDs are long numeric strings that identify users, roles, and servers. To copy them, you first need to enable Developer Mode in Discord:

• Open Discord → User Settings (gear icon) → Advanced → enable Developer Mode
• To get a Role ID: go to Server Settings → Roles, then right-click the role and select "Copy Role ID"
• To get a User ID: right-click any user in the server member list and select "Copy User ID"
• To get your Guild (Server) ID: right-click the server name/icon and select "Copy Server ID"

Features Guide

Auto-Shutdown

CraftDaemon can automatically shut down your Minecraft server when no players have been online for a specified duration. This is especially useful if you're paying for a VPS or cloud server — no one online means no point running it.

Configuration (in config/.env):

• AUTO_STOP_MINUTES — how many idle minutes before the server stops. Set to 0 to disable auto-shutdown entirely
• WARNING_MINUTES — how many minutes before shutdown to post a warning message in your status channel. Must be less than AUTO_STOP_MINUTES
• CHECK_INTERVAL_MS — how often (in milliseconds) the bot checks if the server is idle (default: 30000 = every 30 seconds)

How it works, step by step:

1. The last player leaves the server — player count hits 0
2. The idle countdown timer starts
3. When WARNING_MINUTES remain, the bot posts a warning in the status channel
4. When the full AUTO_STOP_MINUTES expires, CraftDaemon automatically runs /stop (saves world first)

Live Bot Presence

CraftDaemon updates your bot's Discord status in real time to reflect your server state. Anyone in your Discord server can glance at the bot in the member list and immediately know if the server is up without running a command.

Presence states:

• 🔴 Do Not Disturb — Server is offline
• 🟡 Idle — Server is starting up
• 🟢 Online — Shows live player count (e.g. "3 player(s) online")

RCON Manager

CraftDaemon maintains a persistent RCON connection to your Minecraft server rather than opening a new one for every command. This makes queries faster and allows the bot to detect connection drops and recover automatically.

What this handles for you:

• Automatic reconnection if the RCON connection drops (e.g. after a server restart)
• Command queueing so requests don't fail if sent during a brief reconnect window
• Live TPS and player count polling for presence updates
• RCON round-trip latency monitoring shown in /status

Update Notifications

Run /checkupdate at any time to see if a newer version of CraftDaemon is available. The bot fetches the latest release tag from GitHub and compares it to the version currently running. If an update is available, the full changelog from the release notes is shown in the response embed so you know exactly what changed before updating.

Troubleshooting

Bot Won't Start

Commands Not Working

Server Control Issues

Checking Logs

If CraftDaemon is running as a systemd service, view its live logs with:

The -f flag follows the log in real time (like tail -f). Press Ctrl+C to exit. If you want to run the bot directly to see output in your terminal instead (useful for debugging), stop the service first and run:

For Minecraft server logs:

Architecture

System Overview

CraftDaemon sits between Discord and your Minecraft server, translating slash commands into systemd and RCON calls:

Directory Structure

Here's the full layout of the repository and what each file/folder of the bot does:

Key Services

• logger.js: Structured logging with category prefixes, timestamps, and color-coded log levels. Used across all modules — see the Logging section for full details
• rconManager.js: Persistent RCON connection lifecycle — handles connect, keepalive pinging, automatic reconnect on failure, and the command pipeline
• rconQuery.js: Command-facing RCON helpers (e.g. player list, TPS queries) that are wired up after the client is ready
• minecraftSystemd.js: Wraps systemctl calls with a save-all flow before stop/restart operations to prevent data loss
• updateService.js: Polls the GitHub Releases API with ETag caching to compare the running version against the latest tag; delivers update embeds to a configured channel
• commandLock.js: Cooldown guard that prevents rapid repeated start/stop/restart calls within the configured COMMAND_COOLDOWN_MS window
• middleware.js / resolver.js: RBAC enforcement layer — every slash command interaction passes through permissionMiddleware before command.execute() is called
• storage.js: Lightweight JSON persistence for per-guild state (e.g. update notification tracking)

Managing Services

Once both CraftDaemon and your Minecraft server are running, you'll mostly interact with them through Discord slash commands. But you'll occasionally need to manage things directly from the server — here's a reference for every useful command.

systemctl — Controlling Services

These commands let you start, stop, and inspect both the bot and the Minecraft server as systemd services. Replace craftdaemon with minecraft (or whatever you named your service) where applicable.

journalctl — Reading Logs

journalctl reads logs written by systemd services. These are your main tool for debugging when something isn't working as expected.

Logging

CraftDaemon uses a structured logging system with category-based prefixes, timestamps, and color-coded log levels. Every log line tells you when something happened, which component produced it, and how severe it is — making it much easier to trace issues across the bot.

Log Format

Every log entry follows this structure:

For example:

Log Categories

Each category corresponds to a specific part of the bot. You'll see these as the bracketed label after the timestamp:

Log Levels

Changing the Log Level

By default the log level is INFO, which hides DEBUG output. To change it, set LOG_LEVEL in your config/.env:

Valid values: DEBUG, INFO, WARN, ERROR. No code changes or restarts of systemd are needed beyond restarting the bot itself (sudo systemctl restart craftdaemon).

Real Log Examples

Startup configuration summary — printed every time the bot comes online:

A slash command received from Discord:

RCON refused while the server is starting up — the bot throttles repeated refusal logs so they don't flood your output:

Auto-stop engaging — the full idle → warning → shutdown sequence:

Adding Logging to Custom Code

If you're extending CraftDaemon with your own modules, you can use the same logger. Import createLogger and give your component a category name:

Contributing

Want to Help?

CraftDaemon is a solo project and contributions are very welcome! Whether it's bug fixes, new features, documentation improvements, or just suggestions — any input is appreciated.

How to Contribute

1. Fork the repository on GitHub (click "Fork" on the repo page)
2. Clone your fork locally: git clone https://github.com/YOUR_USERNAME/CraftDaemon
3. Create a feature branch: git checkout -b feature/my-feature
4. Make your changes
5. Test thoroughly — make sure existing functionality still works
6. Commit with a clear message: git commit -m "Add my feature"
7. Push to your fork: git push origin feature/my-feature
8. Open a Pull Request on GitHub against the main repo

Reporting Bugs

Found a bug? Open an issue on GitHub Issues. A good bug report includes:

• A clear description of what went wrong
• Steps to reproduce the issue
• What you expected to happen vs what actually happened
• Your environment details: Linux distro, Node.js version (node --version), Minecraft server type
• Relevant log output from journalctl -u craftdaemon if applicable

Code Standards

• Use consistent indentation (2 spaces)
• Write descriptive variable and function names
• Add comments for any complex or non-obvious logic
• Test your changes before submitting
• Follow the existing code style throughout the project

License

CraftDaemon is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.