# nidibot
[](https://pypi.org/project/nidibot) [](https://pypi.org/project/nidibot) [](https://github.com/psf/black) [](https://pypi.python.org/pypi/nidibot/)
## Description
nidibot is a simple to install and configure bot for controlling your game servers from any messaging platform. **Any** is a bit of exaggeration here, since only Discord and Telegram is supported.
**nidibot** name was derived from **Ni**trado, **Di**scord and **bot** - game server provider and messaging platform for which this bot was written originally.
It seems that only Nitrado has a good API for developers available. Any other game server provider does not provide (_pun intended_) any API at all. Some of them provide possibility of managing game server with remote console (RCON) though. RCON support would be a great addition to this project (_someday_).
Any contributions, bug reports and pull requests are welcome!
### Features
* A minimalistic set of fundamental commands - everything you need to run and manage your game server.
* Possibility of connecting unlimited (somewhat) amount of game server providers and bots.
* High extensibility for game server providers and bots - just add a new class for missing game server provider or bot and make a PR.
* Easy setup - install ready-made nidibot package from PyPI and call `initialize_folder()`.
* Simple configuration - everything is located in `bot_configuration.json` file in bot folder. Please see configuration description below for more details.
### Limitations
* Command `/backup_restore` shows only latest 25 backups in Discord bot. This is coming from Discord limitation, it can show only 25 buttons in total (5 rows with 5 buttons each).
* Telegram bot can not notify about game server status changes if 'allowed_channels' is empty. This is coming from Telegram API limitation.
### Commands
nidibot supports following commands:
```batch
/status [OPTIONAL:name]
```
Provides extended status information about game server.
---
```batch
/start [OPTIONAL:name]
```
Starts server if it is offline, restarts server if it is online.
---
```batch
/stop [OPTIONAL:name]
```
Stops server if it is online.
---
```batch
/restart [OPTIONAL:name]
```
Restarts server if it is online, starts server if it is offline.
---
```batch
/backup_create [OPTIONAL:name]
```
Creates backup of games server files. Backed up files are stored in the working folder of bot under **backups** folder.
---
```batch
/backup_list [OPTIONAL:name]
```
Lists available backups of specific game server.
---
```batch
/backup_restore [OPTIONAL:name] [REQUIRED:backup_name]
```
Restores specific backup on a game server.
---
Each command supports optional argument **name**. It is a convenience argument in case you have multiple game servers connected to the bot at once. In case if no name is specified, the command is applied to the first game server in the list.
## Quick start
### Prerequisites
You need to have following before you proceed with the instructions:
1. Virtual machine (VM) or server somewhere in the Internet.
2. Bot account (Discord or Telegram one).
3. Any Discord server or Telegram channel where you have administrative access.
4. Nitrado account (register or login at <https://server.nitrado.net/en-GB/>).
5. Any game server that runs on Nitrado to which you have administrative access.
### Installation
#### Docker
1. Create a `compose.yml` file with the following contents:
```yaml
name: nidibot
services:
nidibot:
container_name: nidibot
image: ghcr.io/thechainercygnus/nidibot:latest
volumes:
- ./backups:/app/backups
- ./logs:/app/logs
restart: unless-stopped
# env_file:
# - .env
# Uncomment to set Environment Variables
# environment:
# - NITRADO_TOKEN=nitrado_api_token
# Uncomment the following to use Discord
# - DISCORD_TOKEN=discord_token
# - DISCORD_PRIVILEGED_USERS=user1,user2 # Can be single or comma separated list
# - DISCORD_ALLOWED_CHANNELS=channel_id_1,channel_id_2 # Can be single or comma separated list
# Uncomment the following to use Telegram
# - TELEGRAM_TOKEN=telegram_atoken
# - TELEGRAM_PRIVILEGED_USERS=user1,user2 # Can be single or comma separated list
# - TELEGRAM_ALLOWED_CHANNELS=channel_id_1,channel_id_2 # Can be single or comma separated list
```
2. Nidibot requires a few environment variables to get up and running. Use only the necessary chat platforms (e.g. if you only need discord, only set the discord settings).
|Variable|Description|Required|
|----|----|----|
|`NITRADO_TOKEN`|Nitrado API Token|**Yes**|
|`DISCORD_TOKEN`|Discord Bot Token|No|
|`DISCORD_PRIVILEGED_USERS`|Comma Separated List of Privileged Discord Usernames|No|
|`DISCORD_ALLOWED_CHANNELS`|Comma Separated List of Allowed Channels for Nidibot to recieve commands in|No|
|`TELEGRAM_TOKEN`|Telegram Bot Token|No|
|`TELEGRAM_PRIVILEGED_USERS`|Comma Separated List of Privileged Telegram Usernames|No|
|`TELEGRAM_ALLOWED_CHANNELS`|Comma Separated List of Allowed Channels for Nidibot to recieve commands in|No|
3. Set required environment variables for your needs using either:
1. .env File method.
a. Delete lines 12-22 of `compose.yml`.
b. Uncomment the remainder of the file.
c. Create a file named `.env` alongside `compose.yml`.
d. Create the file with the needed variables besides `NITRADO_TOKEN` to connect to your services.
2. Set the variables in `compose.yml`.
a. Delete lines 10-12 of `compose.yml`.
b. Uncomment the remainder of the file.
c. Update and Delete lines as needed to configure your instance.
4. Start the bot with `docker compose up -d`
5. Note that it can take up to an hour for the new slash commands to register in your client. This can sometimes be worked around by completely closing and reopening your client.
#### Linux Service
1. Login to your VM or server via SSH.
2. Install Python 3.x. Do this only if Python 3.x is missing or very old. You don't need to have latest Python version for this bot.
3. Install this bot as Python package via pip:
```bash
pip install nidibot
```
4. Or upgrade already installed bot:
```bash
pip install nidibot --upgrade
```
### Configuration
1. Login to your VM or server via SSH.
2. Create new folder for storing bot files.
3. Proceed to the folder.
4. Call following command for initializing bot in this folder and create default configuration files:
```bash
# Ubuntu/Linux only.
python3 -c 'from nidibot import Nidibot; Nidibot.initialize_folder()'
```
5. Open **bot_configuration.json** file in any text editor and modify required values to your own:
```json
{
"general": {
"backups_folder_path": "backups",
"logs_folder_path": "logs"
},
"bots": [
{
"type": "discord",
"token": "your-bot-token",
"privileged_users": [],
"allowed_channels": [],
"notify_polling_seconds": 5
}
],
"server_providers": [
{
"type": "nitrado",
"token": "your-gameserver-api-token",
"timeout_seconds": 10,
"polling_seconds": 5,
"notifications": {
"on_new_server": true,
"on_status_change": true,
"on_address_change": true,
"on_version_change": true,
"on_update_available_change": true
}
}
]
}
```
6. Install **nidibot** service, so it will start automatically every system restart.
```bash
# Ubuntu/Linux only.
sudo cp nidibot.service /etc/systemd/system/nidibot.service && sudo systemctl daemon-reload && sudo systemctl enable nidibot.service
```
7. Start newly installed service:
```bash
# Ubuntu/Linux only.
sudo systemctl start nidibot.service
```
8. Check service status:
```bash
# Ubuntu/Linux only.
sudo systemctl status nidibot.service
```
## Configuration description
The top level of configuration contains:
| Group | Description |
| --- | --- |
| `general` | General parameters of nidibot configuration. |
| `bots` | List of structures describing bot configuration parameters. |
| `server_providers` | List of structures describing game server configuration parameters. |
### General
| Parameter | Description |
| --- | --- |
| `backups_folder_path` | The directory path in which all backups will be stored. Can be both relative or absolute. Default: **"backups"**, relative to bot working directory. |
| `logs_folder_path` | The directory path in which logs will be stored. Can be both relative or absolute. Default: **"logs"**, relative to bot working directory |
### Bot configuration
| Parameter | Description |
| --- | --- |
| `type` | The type of the bot. Allowed values: `discord`, `telegram`. Default: **empty**. |
| `token` | The authentication token required for the bot. Default: **empty**. |
| `privileged_users` | The list of privileged users that can call administrative commands. Default: **empty**. |
| `allowed_channels` | The list of allowed channels from where commands will be accepted and processed. Default: **empty**. |
| `notify_polling_seconds` | The period in seconds for forwarding messages from queue to connected channels. Default: **5**. |
### Server provider configuration
| Parameter | Description |
| --- | --- |
| `type` | The type of the server provider. Allowed values: `nitrado`. Default: **""**. |
| `token` | The authentication token required for the server provider. Default: **""**. |
| `timeout_seconds` | The timeout in seconds for getting a response from the server provider. Default: **10**. |
| `polling_seconds` | The period in seconds for polling a status from the server provider. Default: **5**. |
| `notifications / on_new_server` | Toggles notification on a new game server appearing. Default: **false**. |
| `notifications / on_status_change` | Toggles notification on a game server status change. Default: **false**. |
| `notifications / on_address_change` | Toggles notification on a game server IP address change. Default: **false**. |
| `notifications / on_version_change` | Toggles notification on a game server version change. Default: **false**. |
| `notifications / on_update_available_change` | Toggles notification if game server got an update available. Default: **false**. |
Raw data
{
"_id": null,
"home_page": "https://github.com/thechainercygnus/nidibot",
"name": "nidibot-docker",
"maintainer": "Bryce Jenkins",
"docs_url": null,
"requires_python": "<3.13,>=3.8.0",
"maintainer_email": "bryce@durish.xyz",
"keywords": "discord, nitrado, bot, docker",
"author": "Bryce Jenkins",
"author_email": "bryce@durish.xyz",
"download_url": "https://files.pythonhosted.org/packages/28/b7/77a79d8f1cdd6007f4bd1d262e965b3b28dadf140e6f0e78f1f869616989/nidibot_docker-1.0.2.tar.gz",
"platform": "any",
"description": "# nidibot\n\n[](https://pypi.org/project/nidibot) [](https://pypi.org/project/nidibot) [](https://github.com/psf/black) [](https://pypi.python.org/pypi/nidibot/)\n\n## Description\n\nnidibot is a simple to install and configure bot for controlling your game servers from any messaging platform. **Any** is a bit of exaggeration here, since only Discord and Telegram is supported.\n\n**nidibot** name was derived from **Ni**trado, **Di**scord and **bot** - game server provider and messaging platform for which this bot was written originally.\n\nIt seems that only Nitrado has a good API for developers available. Any other game server provider does not provide (_pun intended_) any API at all. Some of them provide possibility of managing game server with remote console (RCON) though. RCON support would be a great addition to this project (_someday_).\n\nAny contributions, bug reports and pull requests are welcome!\n\n### Features\n\n* A minimalistic set of fundamental commands - everything you need to run and manage your game server.\n* Possibility of connecting unlimited (somewhat) amount of game server providers and bots.\n* High extensibility for game server providers and bots - just add a new class for missing game server provider or bot and make a PR.\n* Easy setup - install ready-made nidibot package from PyPI and call `initialize_folder()`.\n* Simple configuration - everything is located in `bot_configuration.json` file in bot folder. Please see configuration description below for more details.\n\n### Limitations\n\n* Command `/backup_restore` shows only latest 25 backups in Discord bot. This is coming from Discord limitation, it can show only 25 buttons in total (5 rows with 5 buttons each).\n* Telegram bot can not notify about game server status changes if 'allowed_channels' is empty. This is coming from Telegram API limitation.\n\n### Commands\n\nnidibot supports following commands:\n\n```batch\n/status [OPTIONAL:name]\n```\n\nProvides extended status information about game server.\n\n---\n\n```batch\n/start [OPTIONAL:name]\n```\n\nStarts server if it is offline, restarts server if it is online.\n\n---\n\n```batch\n/stop [OPTIONAL:name]\n```\n\nStops server if it is online.\n\n---\n\n```batch\n/restart [OPTIONAL:name]\n```\n\nRestarts server if it is online, starts server if it is offline.\n\n---\n\n```batch\n/backup_create [OPTIONAL:name]\n```\n\nCreates backup of games server files. Backed up files are stored in the working folder of bot under **backups** folder.\n\n---\n\n```batch\n/backup_list [OPTIONAL:name]\n```\n\nLists available backups of specific game server.\n\n---\n\n```batch\n/backup_restore [OPTIONAL:name] [REQUIRED:backup_name]\n```\n\nRestores specific backup on a game server.\n\n---\n\nEach command supports optional argument **name**. It is a convenience argument in case you have multiple game servers connected to the bot at once. In case if no name is specified, the command is applied to the first game server in the list.\n\n## Quick start\n\n### Prerequisites\n\nYou need to have following before you proceed with the instructions:\n\n1. Virtual machine (VM) or server somewhere in the Internet.\n2. Bot account (Discord or Telegram one).\n3. Any Discord server or Telegram channel where you have administrative access.\n4. Nitrado account (register or login at <https://server.nitrado.net/en-GB/>).\n5. Any game server that runs on Nitrado to which you have administrative access.\n\n### Installation\n\n#### Docker\n\n1. Create a `compose.yml` file with the following contents:\n\n```yaml\nname: nidibot\nservices:\n nidibot:\n container_name: nidibot\n image: ghcr.io/thechainercygnus/nidibot:latest\n volumes:\n - ./backups:/app/backups\n - ./logs:/app/logs\n restart: unless-stopped\n # env_file:\n # - .env\n # Uncomment to set Environment Variables\n # environment:\n # - NITRADO_TOKEN=nitrado_api_token\n # Uncomment the following to use Discord\n # - DISCORD_TOKEN=discord_token\n # - DISCORD_PRIVILEGED_USERS=user1,user2 # Can be single or comma separated list\n # - DISCORD_ALLOWED_CHANNELS=channel_id_1,channel_id_2 # Can be single or comma separated list\n # Uncomment the following to use Telegram\n # - TELEGRAM_TOKEN=telegram_atoken\n # - TELEGRAM_PRIVILEGED_USERS=user1,user2 # Can be single or comma separated list\n # - TELEGRAM_ALLOWED_CHANNELS=channel_id_1,channel_id_2 # Can be single or comma separated list\n```\n\n2. Nidibot requires a few environment variables to get up and running. Use only the necessary chat platforms (e.g. if you only need discord, only set the discord settings).\n\n|Variable|Description|Required|\n|----|----|----|\n|`NITRADO_TOKEN`|Nitrado API Token|**Yes**|\n|`DISCORD_TOKEN`|Discord Bot Token|No|\n|`DISCORD_PRIVILEGED_USERS`|Comma Separated List of Privileged Discord Usernames|No|\n|`DISCORD_ALLOWED_CHANNELS`|Comma Separated List of Allowed Channels for Nidibot to recieve commands in|No|\n|`TELEGRAM_TOKEN`|Telegram Bot Token|No|\n|`TELEGRAM_PRIVILEGED_USERS`|Comma Separated List of Privileged Telegram Usernames|No|\n|`TELEGRAM_ALLOWED_CHANNELS`|Comma Separated List of Allowed Channels for Nidibot to recieve commands in|No|\n\n3. Set required environment variables for your needs using either:\n 1. .env File method.\n a. Delete lines 12-22 of `compose.yml`.\n b. Uncomment the remainder of the file.\n c. Create a file named `.env` alongside `compose.yml`.\n d. Create the file with the needed variables besides `NITRADO_TOKEN` to connect to your services.\n 2. Set the variables in `compose.yml`.\n a. Delete lines 10-12 of `compose.yml`.\n b. Uncomment the remainder of the file.\n c. Update and Delete lines as needed to configure your instance.\n4. Start the bot with `docker compose up -d`\n5. Note that it can take up to an hour for the new slash commands to register in your client. This can sometimes be worked around by completely closing and reopening your client.\n\n#### Linux Service\n\n1. Login to your VM or server via SSH.\n2. Install Python 3.x. Do this only if Python 3.x is missing or very old. You don't need to have latest Python version for this bot.\n3. Install this bot as Python package via pip:\n\n```bash\npip install nidibot\n```\n\n4. Or upgrade already installed bot:\n\n```bash\npip install nidibot --upgrade\n```\n\n### Configuration\n\n1. Login to your VM or server via SSH.\n2. Create new folder for storing bot files.\n3. Proceed to the folder.\n4. Call following command for initializing bot in this folder and create default configuration files:\n\n```bash\n# Ubuntu/Linux only.\npython3 -c 'from nidibot import Nidibot; Nidibot.initialize_folder()'\n```\n\n5. Open **bot_configuration.json** file in any text editor and modify required values to your own:\n\n```json\n{\n \"general\": {\n \"backups_folder_path\": \"backups\",\n \"logs_folder_path\": \"logs\"\n },\n \"bots\": [\n {\n \"type\": \"discord\",\n \"token\": \"your-bot-token\",\n \"privileged_users\": [],\n \"allowed_channels\": [],\n \"notify_polling_seconds\": 5\n }\n ],\n \"server_providers\": [\n {\n \"type\": \"nitrado\",\n \"token\": \"your-gameserver-api-token\",\n \"timeout_seconds\": 10,\n \"polling_seconds\": 5,\n \"notifications\": {\n \"on_new_server\": true,\n \"on_status_change\": true,\n \"on_address_change\": true,\n \"on_version_change\": true,\n \"on_update_available_change\": true\n }\n }\n ]\n}\n```\n\n6. Install **nidibot** service, so it will start automatically every system restart.\n\n```bash\n# Ubuntu/Linux only.\nsudo cp nidibot.service /etc/systemd/system/nidibot.service && sudo systemctl daemon-reload && sudo systemctl enable nidibot.service\n```\n\n7. Start newly installed service:\n\n```bash\n# Ubuntu/Linux only.\nsudo systemctl start nidibot.service\n```\n\n8. Check service status:\n\n```bash\n# Ubuntu/Linux only.\nsudo systemctl status nidibot.service\n```\n\n## Configuration description\n\nThe top level of configuration contains:\n\n| Group | Description |\n| --- | --- |\n| `general` | General parameters of nidibot configuration. |\n| `bots` | List of structures describing bot configuration parameters. |\n| `server_providers` | List of structures describing game server configuration parameters. |\n\n### General\n\n| Parameter | Description |\n| --- | --- |\n| `backups_folder_path` | The directory path in which all backups will be stored. Can be both relative or absolute. Default: **\"backups\"**, relative to bot working directory. |\n| `logs_folder_path` | The directory path in which logs will be stored. Can be both relative or absolute. Default: **\"logs\"**, relative to bot working directory |\n\n### Bot configuration\n\n| Parameter | Description |\n| --- | --- |\n| `type` | The type of the bot. Allowed values: `discord`, `telegram`. Default: **empty**. |\n| `token` | The authentication token required for the bot. Default: **empty**. |\n| `privileged_users` | The list of privileged users that can call administrative commands. Default: **empty**. |\n| `allowed_channels` | The list of allowed channels from where commands will be accepted and processed. Default: **empty**. |\n| `notify_polling_seconds` | The period in seconds for forwarding messages from queue to connected channels. Default: **5**. |\n\n### Server provider configuration\n\n| Parameter | Description |\n| --- | --- |\n| `type` | The type of the server provider. Allowed values: `nitrado`. Default: **\"\"**. |\n| `token` | The authentication token required for the server provider. Default: **\"\"**. |\n| `timeout_seconds` | The timeout in seconds for getting a response from the server provider. Default: **10**. |\n| `polling_seconds` | The period in seconds for polling a status from the server provider. Default: **5**. |\n| `notifications / on_new_server` | Toggles notification on a new game server appearing. Default: **false**. |\n| `notifications / on_status_change` | Toggles notification on a game server status change. Default: **false**. |\n| `notifications / on_address_change` | Toggles notification on a game server IP address change. Default: **false**. |\n| `notifications / on_version_change` | Toggles notification on a game server version change. Default: **false**. |\n| `notifications / on_update_available_change` | Toggles notification if game server got an update available. Default: **false**. |\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Simple to install and configure bot for controlling your game servers from any messaging platform. Now available as a docker image.",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/thechainercygnus/nidibot/issues",
"Homepage": "https://github.com/thechainercygnus/nidibot",
"Source Code": "https://github.com/thechainercygnus/nidibot"
},
"split_keywords": [
"discord",
" nitrado",
" bot",
" docker"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3fb5a33831071b26cbc4bb571abb99e5c216e0f5cde8ca81d54a08ed9b708108",
"md5": "a6f88050d4be3593026fff3693699d94",
"sha256": "bbe7c53b36d6081892f0603517218b6f77ba1439153294697ba9062c4301b37f"
},
"downloads": -1,
"filename": "nidibot_docker-1.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6f88050d4be3593026fff3693699d94",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<3.13,>=3.8.0",
"size": 29190,
"upload_time": "2024-09-04T00:05:31",
"upload_time_iso_8601": "2024-09-04T00:05:31.401626Z",
"url": "https://files.pythonhosted.org/packages/3f/b5/a33831071b26cbc4bb571abb99e5c216e0f5cde8ca81d54a08ed9b708108/nidibot_docker-1.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28b777a79d8f1cdd6007f4bd1d262e965b3b28dadf140e6f0e78f1f869616989",
"md5": "cafb4099a044a31d743b3b6b9fad7ea2",
"sha256": "4f519864d422c908bc6904a1495c45e640328c75fa61d1a1dbeab88aaf6e36f6"
},
"downloads": -1,
"filename": "nidibot_docker-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cafb4099a044a31d743b3b6b9fad7ea2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8.0",
"size": 26712,
"upload_time": "2024-09-04T00:05:32",
"upload_time_iso_8601": "2024-09-04T00:05:32.344257Z",
"url": "https://files.pythonhosted.org/packages/28/b7/77a79d8f1cdd6007f4bd1d262e965b3b28dadf140e6f0e78f1f869616989/nidibot_docker-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 00:05:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thechainercygnus",
"github_project": "nidibot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nidibot-docker"
}
JSON
