Files

Raven Scott afb59c82a7 Update post to include API Spec for my-mc

2025-06-26 01:32:32 -04:00

21 KiB

Raw Blame History

Building the My-MC.link Control Panel: A Deep Dive into Its Development and Impact

The My-MC.link Control Panel is a custom-built, feature-rich dashboard designed to manage Minecraft servers with unparalleled ease and efficiency. By integrating seamlessly into the My-MC.link ecosystem, this control panel empowers users to monitor server performance, manage players, configure server properties, and handle mods, all within a sleek, modern interface. In this blog post, we’ll explore the technical intricacies of how the panel was coded, how it functions, and why developing a bespoke solution for My-MC.link is a game-changer for server administrators.

panel

API Docs (Main Service Integration): https://info.my-mc.link/api/

Overview of the My-MC.link Control Panel

The My-MC.link Control Panel is a web-based application that provides a centralized interface for managing Minecraft servers hosted on the My-MC.link platform. Built using a modern tech stack, it leverages Node.js, Express, WebSocket, and Docker on the backend, paired with a responsive HTML/CSS/JavaScript frontend powered by libraries like Chart.js and xterm.js. The panel supports real-time server monitoring, player management, mod installation, SFTP file access, and automated backups, making it a powerful tool for both novice and experienced server administrators.

The decision to custom-code this panel was driven by the need for tight integration with My-MC.link’s infrastructure, ensuring optimal performance, security, and flexibility tailored to the platform’s unique requirements. Let’s break down the development process, key components, and why this custom solution stands out.

Technical Architecture

Backend: Node.js, Express, and WebSocket

The backend is built using Node.js with Express as the web framework, providing a robust foundation for handling HTTP requests and serving the frontend. The server.js file is the entry point, setting up an Express server with middleware like CORS for cross-origin requests, helmet for security headers, and csurf for CSRF protection. It also integrates a WebSocketServer (using the ws library) for real-time communication, enabling features like live server logs and status updates.

Key backend components include:

Docker Integration (includes/docker.js): The panel interacts with Docker containers via the dockerode library to manage Minecraft server instances. Functions like getContainerStats, streamContainerLogs, readServerProperties, writeServerProperties, updateMods, and createBackup provide comprehensive control over server operations, such as monitoring CPU/memory usage, streaming logs, and handling server configurations.
Authentication (includes/auth.js): Secure authentication is implemented using temporary login links generated via generateLoginLink and validated with handleAutoLogin. The system uses HMAC-SHA256 for token generation, rate-limiting to prevent abuse, and sanitize-html to mitigate XSS risks. Environment variables ensure secure configuration, with validation for critical variables like ADMIN_SECRET_KEY.
WebSocket Handling (includes/websocket.js): The WebSocket module manages real-time communication, handling subscriptions to endpoints like docker, docker-logs, and list-players. It supports dynamic updates (e.g., server status, player lists) and static data (e.g., server links). The system uses a clients Map to track active WebSocket connections, ensuring efficient resource management and cleanup on disconnection.
API Requests (includes/api.js): The apiRequest function abstracts HTTP requests to external APIs, using node-fetch with custom headers for authentication. It handles errors gracefully, returning JSON responses with clear success/failure indicators.
Status Checks (includes/status.js): This module monitors server connectivity for Minecraft, Geyser, and SFTP services using external tools and socket connections. It ensures real-time status updates, such as whether the server is online or offline.

Frontend: HTML, CSS, and JavaScript

The frontend, defined in public/index.html and public/js/app.js, is a single-page application (SPA) designed for responsiveness and interactivity. It uses Tailwind CSS for styling, Chart.js for visualizing server metrics (CPU/memory usage), and xterm.js for a terminal-like interface to display server logs. The JavaScript code manages WebSocket connections, UI updates, and user interactions.

Key frontend features include:

Real-Time Monitoring: The panel displays CPU and memory usage via doughnut charts, updated in real-time through WebSocket messages. Server logs are streamed to a terminal interface, providing immediate feedback on server activity.
Player Management: Users can view connected players, send messages, give items, apply effects, teleport players, and perform administrative actions (kick, ban, op, deop) with intuitive buttons and modals.
Mod Management: The panel supports searching, installing, and uninstalling mods via a search interface and a paginated list of installed mods, leveraging the /search, /install, and /uninstall API endpoints.
SFTP Browser: An iframe-based SFTP client allows file management without external tools, using a secure auto-connection mechanism.
Server Configuration: Users can edit server.properties through a dynamic form, with filtered settings to prevent accidental changes to critical configurations.

SFTP Integration

The SFTP Browser is a powerful web-based file management tool that enables seamless interaction with SFTP servers directly within the browser. Forked from kaysting/sftp-browser, it provides a robust interface for navigating, uploading, downloading, and managing files on remote servers. We further enhance this tool with the following features: The backend leverages a temporary connection ID system via the /auto-connection endpoint to establish secure SFTP sessions without exposing sensitive credentials. The frontend, implemented in public/js/app.js, integrates with internal hostname entries to deliver a responsive, browser-based file explorer. Connection details are stored temporarily on the server (with a 12-hour expiration) and in the client’s localStorage for persistence across sessions, ensuring both security and usability.

Source: git.ssh.surf/hypermc/sftp-browser

How It Works

Key Features

Cross-Platform SFTP Connectivity: Connect to SFTP servers hosted on any platform with support for password or private key authentication.
Connection Management: Import/export server connections and manage them via unique connection IDs, with auto-connection URLs (/connect/:connectionId) for credential-free access.
File Operations: Navigate directories, sort files, show/hide hidden files, and switch between list/tile views. Supports drag-and-drop uploads, multi-file downloads as zip, and cut/copy/paste functionality.
File Editing and Viewing: Edit text and Markdown files with syntax highlighting and live previews, and view images, videos, and audio files directly in the browser.
Security Measures: Temporary connection storage with a 12-hour expiration, duplicate connection prevention, and internal IP management for secure Docker container communication.
Mobile Support: Fully responsive UI for seamless use on mobile devices.
API-Driven: JSON-based API endpoints for all operations, with clear success/error responses and authentication headers for secure server communication.

Authentication Flow

Login Link Generation:
- On Page load, the panel initiates a connection by sending the users SFTP Details to the /auto-connection endpoint.
- The backend validates the secret key, generates a secure token using HMAC-SHA256, and stores it in a temporaryLinks Map with an expiration time.
- A unique connectionId is generated and returned with a URL in the format https://sftp.my-mc.link/connect/:connectionId.
- The connect URL is then injected as an iFrame within the panel
- An easy to use one-click button is provided to refresh the SFTP iFrames state if desired.
Auto-Connection:
- When users access the /connect/:connectionId URL, the backend verifies the connectionId and retrieves the associated connection details (host, port, username, password/private key).
- Connection details are stored temporarily on the server (12-hour expiration) and in the client’s localStorage to enable persistent sessions.
- The client uses the stored API key to authenticate WebSocket connections for file operations.
- Duplicate connections are prevented by clearing existing connections when a new /connect/:connectionId URL is accessed.
Internal Container IP Management:
- The hostOS dynamically tracks internal Docker container IPs and dynamically updates the host node’s /etc/hosts file to map container hostnames to their internal IPs. Example:
```
# --- DOCKER CONTAINERS START ---
172.18.0.4 mc_612395330851307520
172.18.0.3 mc_132057503071600640
172.18.0.2 mc_342128351638585344
# --- DOCKER CONTAINERS END ---
```
- This allows secure internal SFTP connections without exposing external IPs, enhancing security by limiting unauthorized access.
- Hostnames in /etc/hosts are used in stored credentials, supporting dynamic IP assignments within Docker.

This is done via a custom service within the Linux Host:

#!/bin/bash

START_MARK="# --- DOCKER CONTAINERS START ---"
END_MARK="# --- DOCKER CONTAINERS END ---"
HOSTS_FILE="/etc/hosts"
TMP_FILE="/tmp/docker-hosts.tmp"

# Root check
if [ "$(id -u)" -ne 0 ]; then
  echo "This script must be run as root."
  exit 1
fi

# Collect Docker container IP/name pairs
docker ps -q | while read -r cid; do
  name=$(docker inspect --format '{{.Name}}' "$cid" | sed 's#^/##')
  ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$cid")
  if [ -n "$ip" ] && [ -n "$name" ]; then
    echo "$ip $name"
  fi
done > "$TMP_FILE"

# If no containers are running, we still want an empty block
[ ! -s "$TMP_FILE" ] && echo "" > "$TMP_FILE"

# Create a new version of the hosts file
awk -v start="$START_MARK" -v end="$END_MARK" '
  BEGIN { inblock = 0 }
  $0 == start { inblock = 1; print start; while ((getline line < "/tmp/docker-hosts.tmp") > 0) print line; print end; skip = 1; next }
  $0 == end { inblock = 0; skip = 1; next }
  skip == 1 && $0 != end { next }
  { print }
' "$HOSTS_FILE" > "${HOSTS_FILE}.new"

# If no start marker found, append block to the end
if ! grep -qF "$START_MARK" "$HOSTS_FILE"; then
  echo "$START_MARK" >> "${HOSTS_FILE}.new"
  cat "$TMP_FILE" >> "${HOSTS_FILE}.new"
  echo "$END_MARK" >> "${HOSTS_FILE}.new"
fi

# Move new file into place
mv "${HOSTS_FILE}.new" "$HOSTS_FILE"
rm -f "$TMP_FILE"

Optional External SFTP Access:
- Users can start a free Jump Host SFTP Port for external access using clients like FileZilla or WinSCP, providing flexibility to the users.

Security Measures

Temporary Connection Storage: Connection details are stored server-side for only 12 hours, reducing the risk of unauthorized access.
Secure Token Generation: HMAC-SHA256 tokens ensure login links are tamper-proof and time-limited.
Client-Side Security: Credentials are stored in localStorage only for the duration of the session, with automatic cleanup on new connections.

My-MC.Link Real-Time Updates

The WebSocket connection is the backbone of the panel’s real-time capabilities.

Upon connecting, the client subscribes to multiple endpoints (docker, docker-logs, list-players, etc.).

The backend pushes updates for:

Server Metrics: CPU and memory usage are polled every second and sent to the client, updating the Chart.js doughnut charts.
Logs: Docker container logs are streamed to the xterm.js terminal, with cleanup to remove timestamps and color codes for readability.
Player Lists: The /list-players endpoint provides real-time updates on connected players, enabling dynamic management actions.
Status Checks: The panel monitors Minecraft, Geyser, and SFTP connectivity, displaying status icons (✅/❌) to indicate online/offline states.

Docker Integration

The panel interacts with Docker containers to manage Minecraft servers.

Each user is associated with a specific container (named after their username), allowing the panel to:

Retrieve real-time stats (CPU/memory usage) using getContainerStats.
Stream logs with streamContainerLogs, handling reconnection if the container restarts.
Read and write server.properties using readServerProperties and writeServerProperties.
Update mods with updateMods, executing a mod-manager update command in the container.
Create backups with createBackup, generating a download URL for the backup file.

Mod Management

The Mod Management system integrates with an external CLI utility—mod-manager—to provide streamlined control over mods on Fabric Minecraft Servers. This system interfaces with Modrinth and Curseforge APIs to support installing, updating, and migrating mods. This tool integrates with the panel via the built in docker integration.

Source: https://git.ssh.surf/snxraven/mod-manager

Frontend Panel Behavior

Search Interface: Users can search for mods with debounced input, providing a smooth experience.
Pagination: Both search results and installed mods are paginated to maintain performance and usability.
Action Guarding: Mod-related operations are only allowed on running containers to ensure stability.

Backend Functionality

Validates container state before proceeding with install, uninstall, update, or migration commands.
Interacts with mod-manager, a local CLI utility installed at /home/mc/minecraft/mod-manager.

About `mod-manager`

A Node.js- and Shell-based CLI tool for managing Fabric Minecraft Server mods with package-manager-like features.

🔧 Key Features

Install mods from Modrinth and Curseforge
Uninstall installed mods
Update mods with a single command
Migrate mods to a new Minecraft version
Mark mods as essential (prevent unintentional removal)

🧪 Usage Examples

# Initialize mod-manager
$ mod-manager init
? What Minecraft version is your server running? 1.19.1
✔ Successfully initialised Mod Manager!

# Install a mod (e.g., Lithium)
$ mod-manager install lithium
✔ Successfully installed Lithium

# List installed mods
$ mod-manager list
Name    | Id       | File Name                         | Version        | Source   | Essential | Dependencies
-------------------------------------------------------------------------------------------------------------
Lithium | gvQqBUqZ | lithium-fabric-mc1.19.2-0.8.3.jar | mc1.19.2-0.8.3 | Modrinth | false     |

🖥️ Commands

Usage: mod-manager [options] [command]

A package (mod) manager for Fabric Minecraft Servers

Options:
  -v, --version                         Reports the server's Minecraft version
  -h, --help                            Displays help

Commands:
  init                                  Initializes mod-manager
  install [options] <mods...>           Installs one or more mods
  list                                  Lists all installed mods
  uninstall <mods...>                   Removes one or more mods
  essential <mods...>                   Marks mods as essential or not
  update                                Updates all outdated mods
  migrate-possible [options] [version]  Checks if migration is possible to a given Minecraft version
  migrate [options] [version]           Migrates all mods to a target Minecraft version
  help [command]                        Help for a specific command

Why Custom Coding Matters

Building the My-MC.link Control Panel from scratch offers several advantages over using off-the-shelf solutions:

Tailored Integration: The panel is designed specifically for My-MC.link’s infrastructure, ensuring seamless interaction with Docker containers, custom APIs, and the platform’s authentication system. This eliminates compatibility issues and optimizes performance.
Security First: Custom coding allowed us to implement robust security measures, including HMAC-based token generation, rate-limiting, CSRF protection, and CSP with nonces. These features protect against common web vulnerabilities and ensure user data safety.
Real-Time Capabilities: The WebSocket-driven architecture enables real-time updates for server metrics, logs, and player status, providing a dynamic user experience that generic panels often lack.
Feature Flexibility: The panel supports unique features like the SFTP browser, mod management, and automated backups, tailored to the needs of Minecraft server administrators. Custom development allowed us to prioritize these features and integrate them seamlessly.
Scalability and Maintenance: By owning the codebase, the My-MC.link team can easily extend the panel with new features, optimize performance, and address issues without relying on third-party vendors. The open-source nature (available at https://git.ssh.surf/hypermc/panel) encourages community contributions and transparency.
User Experience: The frontend is crafted with a focus on usability, featuring a responsive design, intuitive modals, and real-time feedback. Libraries like Tailwind CSS and Chart.js enhance the visual appeal and functionality, making server management accessible to all users.

Challenges and Solutions

Challenge: Real-Time Log Streaming

Streaming Docker container logs in real-time while handling container restarts and connection drops was complex. The streamContainerLogs function needed to manage log streams efficiently and reconnect automatically.

Solution: We implemented a robust streaming mechanism in includes/docker.js, using Docker’s logs API with follow: true. A monitoring interval checks container status and restarts the stream if necessary. The frontend uses xterm.js to display logs cleanly, with automatic scrolling to keep the latest logs visible.

Challenge: Secure Authentication

Ensuring secure authentication without storing sensitive data on the client side was critical. Temporary login links needed to be both secure and user-friendly.

Solution: The generateLoginLink and handleAutoLogin functions use HMAC-SHA256 for token generation, with IP and user-agent verification to prevent unauthorized access. Temporary links expire after a configurable period, and credentials are stored securely in localStorage only after validation.

Challenge: SFTP Integration

Providing a browser-based SFTP client without exposing credentials or requiring external software was a significant hurdle.

Solution: The auto-connection endpoint (/auto-connection) generates temporary connection IDs, and the frontend integrates with an internal SFTP service per container. Credentials are transmitted securely via POST requests, and the iframe-based client ensures a seamless user experience.

Challenge: Resource Management

Managing multiple WebSocket connections and intervals for real-time updates could lead to resource leaks if not handled properly.

Solution: The clients Map tracks active connections, and all intervals (e.g., for Docker stats, status checks) are cleared on connection close. The backend also implements cleanup for temporary links and log streams, ensuring efficient resource usage.

Impact on the My-MC.link Ecosystem

The custom-coded control panel has transformed the My-MC.link ecosystem by:

Simplifying Server Management: Administrators can monitor and control their servers from a single interface, reducing the need for multiple tools.
Enhancing Accessibility: The browser-based SFTP client and mod management system make advanced server administration accessible to users without technical expertise.
Improving Reliability: Real-time monitoring and easy to trigger backups ensure servers remain operational and data is protected.
Fostering Community Engagement: The open-source codebase invites contributions, fostering a community-driven approach to feature development.
Setting a Standard: The panel’s sleek design and robust functionality set a new standard for Minecraft server management, differentiating My-MC.link from competitors.

My thoughts

The My-MC.link Control Panel is a testament to the power of custom development. By building a tailored solution, the team has created a robust, secure, and user-friendly platform that enhances the Minecraft server management experience. Its seamless integration with Docker, real-time WebSocket updates, and innovative features like the SFTP browser make it a standout in the Minecraft hosting ecosystem. As an open-source project, it invites collaboration and continuous improvement, ensuring it remains a cornerstone of My-MC.link’s offerings. Whether you’re a casual server owner or a seasoned administrator, the My-MC.link Control Panel is an indispensable tool for managing your Minecraft world.

21 KiB Raw Blame History Unescape Escape