user-installable-app/README.md
2024-10-02 18:38:03 -04:00

381 lines
8.1 KiB
Markdown

# Discord Container Manager Bot
A powerful Discord bot built with [discord.js](https://discord.js.org/) that allows users to manage and interact with containerized services directly from Discord. The bot integrates with a MySQL database for user management and communicates with an external API to perform various container operations such as starting, stopping, restarting containers, fetching stats, and executing commands.
## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Config Files](#config-files)
- [Database Setup](#database-setup)
- [Usage](#usage)
- [Available Commands](#available-commands)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Features
- **Slash Commands:** Interact with containers using intuitive slash commands.
- **Database Integration:** Securely manage user data with MySQL.
- **API Communication:** Fetch and manage tokens automatically, ensuring secure API interactions.
- **Dynamic Command Registration:** Automatically registers and updates commands with Discord.
- **Embed Messages:** Provides rich and informative responses using Discord embeds.
- **Command Execution:** Execute shell commands within containers directly from Discord.
## Prerequisites
Before you begin, ensure you have met the following requirements:
- **Node.js:** Version 16.6.0 or higher. [Download Node.js](https://nodejs.org/)
- **MySQL Database:** A running MySQL server to store user data.
- **Discord Bot:** A Discord application with a bot token. [Create a Discord Bot](https://discord.com/developers/applications)
## Installation
1. **Clone the Repository**
```bash
git clone https://github.com/yourusername/discord-container-manager.git
cd discord-container-manager
```
2. **Install Dependencies**
Ensure you have [Node.js](https://nodejs.org/) installed. Then, install the required npm packages:
```bash
npm install
```
The project relies on the following main dependencies:
- `discord.js`: Interact with the Discord API.
- `mysql2`: Connect to the MySQL database.
- `jsonfile`: Read and write JSON files.
- `unirest`: Make HTTP requests.
- `fs`: File system operations (built-in Node.js module).
## Configuration
### Config Files
The bot requires two main configuration files: `config.json` and `tokens.json`.
1. **config.json**
This file holds essential configuration details such as Discord tokens, API endpoints, and database credentials.
```json
{
"token": "YOUR_DISCORD_BOT_TOKEN",
"clientId": "YOUR_DISCORD_CLIENT_ID",
"SQLHOST": "localhost",
"SQLUSER": "your_mysql_user",
"SQLDATABASE": "your_database",
"SQLPASSWORD": "your_mysql_password",
"endpoint": "https://api.yourservice.com",
"password": "YOUR_API_PASSWORD",
"apiBaseURL": "https://api.yourservice.com"
}
```
- **token:** Your Discord bot token.
- **clientId:** Your Discord application's client ID.
- **SQLHOST:** Hostname for your MySQL server.
- **SQLUSER:** MySQL username.
- **SQLDATABASE:** Name of the MySQL database.
- **SQLPASSWORD:** MySQL user password.
- **endpoint:** API endpoint for token fetching.
- **password:** Password used for API authentication.
- **apiBaseURL:** Base URL for the API interactions.
2. **tokens.json**
This file is used to store and manage user-specific API tokens. It's automatically generated and managed by the bot. **Ensure this file is kept secure and is excluded from version control.**
```json
{}
```
> **Note:** It's recommended to add `tokens.json` and `config.json` to your `.gitignore` to prevent sensitive information from being pushed to version control.
### Database Setup
The bot connects to a MySQL database to manage user data. Ensure your database has a `users` table with the following structure:
```sql
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
uid VARCHAR(255) NOT NULL,
discord_id VARCHAR(255) UNIQUE NOT NULL
);
```
- **id:** Primary key.
- **uid:** Unique identifier for the user in the external system.
- **discord_id:** Discord user ID.
> **Note:** Adjust the table schema as needed based on your requirements.
## Usage
After completing the installation and configuration steps, you can start the bot using:
```bash
node index.js
```
Upon successful startup, the bot will register its slash commands with Discord and begin listening for interactions.
### Available Commands
The bot offers a variety of slash commands to manage containers and interact with the underlying API.
#### `/hello`
**Description:** Say hello via API.
**Usage:**
```
/hello
```
**Response:**
An embed message with a greeting from the API.
#### `/name`
**Description:** Get the API username.
**Usage:**
```
/name
```
**Response:**
An embed message displaying the API username.
#### `/start`
**Description:** Start the container.
**Usage:**
```
/start
```
**Response:**
An embed message confirming the container has started.
#### `/stop`
**Description:** Stop the container.
**Usage:**
```
/stop
```
**Response:**
An embed message confirming the container has stopped.
#### `/restart`
**Description:** Restart the container.
**Usage:**
```
/restart
```
**Response:**
An embed message confirming the container has restarted.
#### `/info`
**Description:** Get container information.
**Usage:**
```
/info
```
**Response:**
An embed message detailing various information about the container, including name, IP address, memory usage, CPU usage, status, and more.
#### `/stats`
**Description:** Get container stats.
**Usage:**
```
/stats
```
**Response:**
An embed message displaying memory and CPU usage statistics of the container.
#### `/time`
**Description:** Get container expire time.
**Usage:**
```
/time
```
**Response:**
An embed message showing the expiration date of the container.
#### `/root-password`
**Description:** Change the root password.
**Usage:**
```
/root-password
```
**Response:**
An ephemeral embed message revealing the new root password.
#### `/new-api-key`
**Description:** Generate a new API key.
**Usage:**
```
/new-api-key
```
**Response:**
An ephemeral embed message providing a new API key.
#### `/key-expire-time`
**Description:** Check the API key expiration time.
**Usage:**
```
/key-expire-time
```
**Response:**
An ephemeral embed message showing the expiration date of the API key.
#### `/x`
**Description:** Execute a command in the container.
**Usage:**
```
/x command: <your_command>
```
**Options:**
- **command** (String, Required): The command to execute inside the container.
**Response:**
A message containing the standard output and error from the executed command, formatted in markdown code blocks.
**Examples:**
- Change directory:
```
/x command: cd /var/www
```
- List files:
```
/x command: ls -la
```
#### `/notify`
**Description:** Send a notification to Discord.
**Usage:**
```
/notify message: <your_message>
```
**Options:**
- **message** (String, Required): The message to send as a notification.
**Response:**
An ephemeral embed message confirming the notification has been sent.
## Contributing
Contributions are welcome! Follow these steps to contribute:
1. **Fork the Repository**
Click the [Fork](https://github.com/yourusername/discord-container-manager/fork) button on the repository page.
2. **Create a New Branch**
```bash
git checkout -b feature/YourFeature
```
3. **Make Your Changes**
Implement your feature or fix the bug.
4. **Commit Your Changes**
```bash
git commit -m "Add your message here"
```
5. **Push to the Branch**
```bash
git push origin feature/YourFeature
```
6. **Create a Pull Request**
Navigate to the original repository and create a pull request from your forked branch.
## Acknowledgments
- [discord.js](https://discord.js.org/) - Powerful library for interacting with the Discord API.
- [Unirest](http://unirest.io/) - Lightweight HTTP client.
- [mysql2](https://github.com/sidorares/node-mysql2) - MySQL client for Node.js.
- [jsonfile](https://github.com/jprichardson/node-jsonfile) - Easily read/write JSON files.