panel/README.md

# 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 express cors ws dockerode node-fetch unirest dotenv
   ```

3. **Set Up Environment Variables**

   Create a `.env` file in the root directory and configure the required variables (see [Configuration](#configuration)).

4. **Update package.json**

   Ensure your `package.json` includes `"type": "module"` to enable ES modules:

   ```json
   {
     "type": "module",
     "scripts": {
       "start": "node index.js"
     }
   }
   ```

5. **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
├── includes/
│   ├── api.js                   # API request handling
│   ├── auth.js                  # Authentication and login link logic
│   ├── docker.js                # Docker-related functions
│   ├── status.js                # Connection status checking functions
│   ├── websocket.js             # WebSocket connection handling
├── index.js                     # Main server entry point
├── app.js                       # Frontend JavaScript logic
├── .env                         # Environment variables (not tracked)
├── package.json                 # Node.js dependencies
└── README.md                    # Project documentation
```


## Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch (`git checkout -b feature/your-feature`).
3. Make your changes and commit (`git commit -m "Add your feature"`).
4. Push to your branch (`git push origin feature/your-feature`).
5. Open a pull request on the [repository](https://git.ssh.surf/hypermc/panel).

Please ensure your code follows the project's coding style and includes appropriate tests.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Acknowledgments

- **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).