nc_tg_bot

🤖 About Nextcloud Telegram Bot

This Telegram bot simplifies the process of interacting with Nextcloud, allowing users to easily share files without navigating the Nextcloud interface directly. It also provides the following functionalities:

• File management: users can navigate through the file hierarchy and manage files and folders.
• Trash bin management: users can restore or delete files from the trash bin.
• Search by name: users can search for files by their name.

Much more can be easily implemented using the nc_py_api and aigoram libraries.

❓Motivation

I created a Telegram bot to simplify sharing memes on Nextcloud for myself and friends. It provides a user-friendly interface for efficient communication and collaboration. The project streamlines the sharing process and enhances efficiency. This experience will be valuable in my future projects involving external service integration with Telegram.

🚀 How to Use

There is an example in this repository, you can use it as a guide.

💡Installation presupposes that Nextcloud is already installed and configured.

• First of all, you need to clone the repository and go to it:

git clone https://github.com/blvdek/nc_tg_bot.git
cd nc_tg_bot

🐳 Running in Docker (recommended method)

• Create and edit .env file:

cp .env.exmaple .env
vi .env

• Start services:

docker compose up -d

💻 Running on Local Machine

• Install dependencies using Poetry:

poetry install

• Start the necessary services (at least the database and redis)

• Create and edit .env file:

cp .env.exmaple .env
vi .env

• Make migrations:

make migrate

• Start telegram bot:

poetry run python -m bot

🌍 Environment variables

To launch the bot you only need a token bot, database, Redis and Nextcloud settings, everything else can be left out. For more information, see .env.example.

☁️ Docker and Nextcloud

To use the Nextcloud Telegram bot with Nextcloud, you can create a Docker Compose file that runs on the same Docker network as Nextcloud. This allows the bot to communicate with Nextcloud internally.

To do this, you need to set the NC__PROTOCOL, NC__HOST and NC__PORT environment variables in your Docker Compose file or .env. These variables are used for internal communication between bot and Nextcloud.

If the internal and external host are different, you can set the NC__OVERWRITE__PROTOCOL, NC__OVERWRITE__HOST and NC__OVERWRITE__PORT variables. These variables are used for the external access link that the bot will send.

If your NC__PROTOCOL, NC__HOST and NC__PORT are already accessible from outside, you don't need to specify NC__OVERWRITE__PROTOCOL, NC__OVERWRITE__HOST and NC__OVERWRITE__PORT. In this case, the bot will use NC__PROTOCOL, NC__HOST and NC__PORT as the external access points.

💡For example, you set the parameters of the docker internal network for NC__HOST and other default variables, then links of the following type will be created: http://nextcloud:80/... The user will not be able to open such links in browser, but if you specify OVERWRITE, the host will be replaced with OVERWRITE and the links will look like, for example: https://exmaple.com:80/... and the user will already be able to open such links in his browser.

Here's an example of how you can configure this in your Docker Compose file:

services:

...

# For example, here is an NGINX container that receives an ssl certificate
# and indicates that the domain "example.com" points to the Nextcloud container.

...

  nextcloud:
    image: nextcloud
    ports:
      - 8080:80
    volumes:
      - nextcloud-data:/var/www/html
    networks:
      - nextcloud-network

...

volumes:
  nextcloud-data:

networks:
  nextcloud-network:
    name: nextcloud-network
    driver: bridge

Docker compose file with bot:

services:

...

  bot:
    image: bagoont/nc_tg_bot
    restart: always
    env_file: .env
    environment:
      NC__HOST: "nextcloud"
      NC__OVERWRITE__PROTOCOL: "https"
      NC__OVERWRITE__HOST: "example.com"
      NC__OVERWRITE__PORT: 80
    volumes:
      - data:/var/www/html
    network:
      - nextcloud-host-network

...

volumes:
  data:

networks:
  nextcloud-host-network:
    name: nextcloud-network
    external: true

⚙️ Tech Stack

• poetry — development workflow.
• docker — to automate deployment.
• postgres — powerful, open source object-relational database system.
• asyncpg — a fast PostgreSQL Database Client Library for Python/asyncio.
• alembic — a database migrations tool for SQLAlchemy.
• redis — in-memory data structure store used as a cache and FSM.
• aiogram — asynchronous framework for Telegram Bot API.
• aiogram_i18n — middleware for Telegram bot internationalization.
• fluent-runtime — a localization system.
• pydantic-settings — settings management using pydantic.
• sqlalchemy — object-relational mapping (ORM) library that provides a set of high-level API for interacting with relational databases
• uvloop — ultra fast asyncio event loop.
• nc-py-api — Nextcloud Python framework.
• mypy — optional static typing for Python.
• ruff — an extremely fast Python linter and code formatter, written in Rust.
• pre-commit — a framework for managing and maintaining multi-language pre-commit hooks.

⭐ Support

If you find this project useful, you can support it in the following ways:

• 🌟 Star the repository.
• 💬 Contribute to the project.
• 📣 Share this project on social media.

❗ More information

• Contribute
  • Discussions
  • Issues