307 lines
21 KiB
Markdown
307 lines
21 KiB
Markdown
<!-- lead -->
|
||
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.
|
||
|
||
# Source: https://git.ssh.surf/hypermc/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](https://github.com/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](https://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
|
||
|
||
1. **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.
|
||
|
||
2. **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.
|
||
|
||
3. **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:
|
||
|
||
```bash
|
||
#!/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"
|
||
```
|
||
|
||
4. **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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
1. **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.
|
||
|
||
2. **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.
|
||
|
||
3. **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.
|
||
|
||
4. **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.
|
||
|
||
5. **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.
|
||
|
||
6. **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.
|