Add README.md

2025-06-16 10:28:09 -04:00
parent f272619fba
commit fb0eb5ed44
1 changed files with 170 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,170 @@
+# HyperMC Panel
+
+Welcome to **HyperMC Panel**, a powerful and user-friendly web-based control panel for managing Minecraft servers with ease. Built with modern technologies like Node.js, Express, WebSocket, and Docker, this panel provides real-time server monitoring, mod management, player administration, and seamless integration with Minecraft server features. Whether you're a server admin or a casual player, HyperMC Panel simplifies server management with an intuitive interface and robust functionality.
+
+## Features
+
+- **Real-Time Monitoring**: Track server status, CPU, and memory usage with live-updating charts powered by Chart.js.
+- **Server Control**: Start, stop, restart, and edit server properties (`server.properties`) directly from the panel.
+- **Player Management**: Kick, ban, op, deop, send private messages, and give items to players with pre-configured loadouts or custom items.
+- **Mod Management**: Search, install, and uninstall mods effortlessly with an integrated mod search system.
+- **Console Access**: Send RCON commands and view real-time server logs in a sleek terminal interface using xterm.js.
+- **Link Generation**: Create temporary connection links for Minecraft, Geyser (Bedrock support), and SFTP access with status indicators.
+- **Docker Integration**: Manage Docker containers for your Minecraft server, including stats and logs.
+- **WebSocket Communication**: Ensures low-latency, real-time updates for all server activities.
+- **Secure Authentication**: API key-based login with temporary auto-login links for admins.
+- **Responsive Design**: A modern, Tailwind CSS-styled interface that works seamlessly on desktop and mobile devices.
+
+## Tech Stack
+
+- **Backend**: Node.js, Express.js, WebSocket (ws), Dockerode, node-fetch, unirest
+- **Frontend**: HTML, JavaScript, Tailwind CSS, Chart.js, xterm.js, FitAddon
+- **Environment Management**: dotenv for configuration
+- **Other Tools**: crypto for secure link generation, child_process for executing status checks
+
+## Prerequisites
+
+Before setting up HyperMC Panel, ensure you have the following installed:
+
+- **Node.js** (v16 or higher)
+- **Docker** (for container management)
+- **Git** (to clone the repository)
+- A running Minecraft server with Docker support
+- Access to an authentication endpoint for API key generation
+- Environment variables configured (see [Configuration](#configuration))
+
+## Installation
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://git.ssh.surf/hypermc/panel.git
+   cd panel
+   ```
+
+2. **Install Dependencies**
+
+   ```bash
+   npm install
+   ```
+
+3. **Set Up Environment Variables**
+
+   Create a `.env` file in the root directory and configure the required variables (see [Configuration](#configuration)).
+
+4. **Start the Server**
+
+   ```bash
+   npm start
+   ```
+
+   The panel will be accessible at `http://localhost:<PORT>` (default port is defined in your `.env` file).
+
+## Configuration
+
+Create a `.env` file in the project root with the following variables:
+
+```env
+# Docker configuration
+DOCKER_SOCKET_PATH=/var/run/docker.sock
+
+# API and server settings
+API_URL=https://api.example.com
+PORT=3000
+ADMIN_SECRET_KEY=your_secure_secret_key
+LINK_EXPIRY_SECONDS=3600
+
+# Authentication endpoint
+AUTH_ENDPOINT=https://auth.example.com/token
+AUTH_PASSWORD=your_auth_password
+
+# File paths and directories
+STATUS_CHECK_PATH=/path/to/status-check
+GEYSER_STATUS_CHECK_PATH=/path/to/geyser-status-check
+SERVER_PROPERTIES_PATH=/minecraft/server.properties
+TEMP_DIR=/tmp
+CONTAINER_TEMP_FILE_PREFIX=/tmp/
+TEMP_FILE_RANDOM_ID_BYTES=16
+LINK_ID_BYTES=16
+AUTO_LOGIN_LINK_PREFIX=https://panel.example.com/auto-login/
+AUTO_LOGIN_REDIRECT_URL=https://panel.example.com
+
+# WebSocket and polling intervals (in milliseconds)
+LOG_STREAM_MONITOR_INTERVAL_MS=5000
+CONNECTION_STATUS_INTERVAL_MS=10000
+GEYSER_STATUS_INTERVAL_MS=10000
+SFTP_STATUS_INTERVAL_MS=10000
+CONTAINER_STATUS_MONITOR_INTERVAL_MS=5000
+DYNAMIC_ENDPOINTS_INTERVAL_MS=60000
+STATIC_ENDPOINTS_INTERVAL_MS=300000
+LIST_PLAYERS_INTERVAL_MS=10000
+DOCKER_STATS_INTERVAL_MS=5000
+SFTP_CONNECTION_TIMEOUT_MS=5000
+TEMP_LINKS_CLEANUP_INTERVAL_MS=60000
+CONNECTION_STATUS_NEW_USER_INTERVAL_MS=10000
+LIST_PLAYERS_NEW_USER_INTERVAL_MS=10000
+
+# Log streaming
+LOG_STREAM_TAIL_LINES=100
+
+# SFTP settings
+SFTP_HOSTNAME=sftp.example.com
+```
+
+Replace placeholder values (e.g., `https://api.example.com`, `your_secure_secret_key`) with your actual configuration.
+
+## Usage
+
+1. **Access the Panel**
+
+   Open your browser and navigate to `http://localhost:<PORT>` or your configured domain. Log in using a valid API key or generate a temporary login link via the `/generate-login-link` endpoint (requires `ADMIN_SECRET_KEY`).
+
+2. **Manage Your Server**
+
+   - **Server Status**: View real-time CPU, memory, and server status.
+   - **Player Management**: Interact with players using the provided buttons (kick, ban, op, etc.).
+   - **Mod Management**: Search for mods, install them, or uninstall existing ones.
+   - **Console**: Send RCON commands and monitor logs in the terminal.
+   - **Links**: Generate connection, Geyser, or SFTP links and check their online status.
+   - **Server Properties**: Edit `server.properties` with a user-friendly form.
+
+3. **Generate Auto-Login Links**
+
+   Admins can generate temporary login links by sending a POST request to `/generate-login-link` with the following JSON body:
+
+   ```json
+   {
+     "secretKey": "your_admin_secret_key",
+     "username": "desired_username"
+   }
+   ```
+
+   The response will include a `loginLink` valid for the duration specified in `LINK_EXPIRY_SECONDS`.
+
+## Folder Structure
+
+```
+├── public/
+│   ├── css/
+│   │   └── styles.min.css       # Compiled Tailwind CSS
+│   ├── favicon/                 # Favicon assets
+│   └── index.html               # Main HTML file
+├── app.js                       # Frontend JavaScript logic
+├── server.js                    # Backend server logic
+├── .env                         # Environment variables (not tracked)
+├── package.json                 # Node.js dependencies
+└── README.md                    # Project documentation
+```
+
+
+- **Chart.js**: For beautiful, responsive charts.
+- **xterm.js**: For the terminal interface.
+- **Tailwind CSS**: For the sleek, modern UI.
+- **Dockerode**: For seamless Docker integration.
+- **SNXRaven**: For creating this project with ❤️ ([raven-scott.fyi](https://raven-scott.fyi)).
+
+## Contact
+
+For questions, issues, or suggestions, please open an issue on the [repository](https://git.ssh.surf/hypermc/panel) or contact the maintainer at [raven-scott.fyi](https://raven-scott.fyi).
+
+Happy server management with HyperMC Panel! 🚀